Relay docs
API ReferenceConversations

Create a conversation

Creates a new conversation for an existing contact. Requires the `conversations:write` scope.

POST
/v1/public/conversations

Authorization

bearerAuth
AuthorizationBearer <token>

Workspace API key, e.g. rl_live_….

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

contactId*string

Contact the conversation belongs to.

Formatuuid
inboxId?string

Inbox to attach the conversation to. Defaults to the workspace's first inbox when omitted.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/public/conversations" \  -H "Content-Type: application/json" \  -d '{    "contactId": "b5ec5d98-4bee-4da1-ad24-dde86346cb1d"  }'
{  "id": "9b2c1f7e-3d4a-4c1b-8e2f-1a2b3c4d5e6f",  "status": "open",  "priority": "high",  "labels": [    "vip",    "billing"  ],  "unreadCount": 2,  "contact": {    "id": "c0ffee00-1111-2222-3333-444455556666",    "name": "Ada Lovelace",    "email": "[email protected]",    "phoneNumber": null,    "shopName": "acme.myshopify.com"  },  "inbox": {    "id": "1b0a7d22-aaaa-bbbb-cccc-ddddeeeeffff",    "name": "Web widget",    "channelType": "web_widget"  },  "assignee": {    "id": "user_2x9Q",    "name": "Grace Hopper",    "image": "https://cdn.relay.app/u/grace.png"  },  "lastActivityAt": "2026-06-25T10:12:00.000Z",  "createdAt": "2026-06-24T08:00:00.000Z"}
{  "error": "string"}
{  "error": "string"}
{  "error": "string"}
{  "error": "string"}

Add a message to a conversation POST

Appends a message to a conversation. The message is delivered live to connected dashboard agents through the same realtime fan-out as the rest of the product. Requires the `conversations:write` scope.

Get a contact GET

Returns a single contact. Requires the `contacts:read` scope.