Create conversation

POST

/v1/messaging/conversations

POST

/v1/messaging/conversations

$ curl -X POST https://api.runtype.com/v1/messaging/conversations \
>      -H "Authorization: <apiKey>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "surfaceId": "surf_9a8b7c6d5e4f3g2h1i0j"
> }'

1 {
2   "agentMode": "automated",
3   "createdAt": "2024-06-01T10:15:30Z",
4   "externalParticipantId": "user_1234567890abcdef",
5   "externalThreadId": "thread_0987654321fedcba",
6   "id": "conv_abcdef1234567890",
7   "lastMessageAt": "2024-06-01T10:20:45Z",
8   "messageCount": 3,
9   "participantEmail": "jane.doe@example.com",
10   "participantName": "Jane Doe",
11   "status": "open",
12   "subject": "Inquiry about product features",
13   "surfaceId": "surf_9a8b7c6d5e4f3g2h1i0j",
14   "takeoverActorId": "agent_0011223344556677",
15   "takeoverActorType": "human_agent",
16   "takeoverAt": "2024-06-01T10:18:00Z",
17   "takeoverReason": "Customer requested human assistance",
18   "timezone": "America/New_York",
19   "updatedAt": "2024-06-01T10:21:00Z",
20   "context": {},
21   "participantMetadata": {},
22   "surface": {
23     "id": "surf_9a8b7c6d5e4f3g2h1i0j",
24     "name": "Customer Support Chat",
25     "type": "webchat"
26   }
27 }

Create a new messaging conversation linked to a surface.

Authentication

AuthorizationBearer

API key or Clerk session token

Request

This endpoint expects an object.

surfaceIdstringRequired

contextobjectOptional

externalParticipantIdstringOptional<=500 characters

externalThreadIdstringOptional<=500 characters

participantEmailstringOptionalformat: "email"<=255 characters

participantMetadatamap from strings to anyOptional

participantNamestringOptional<=255 characters

statusenumOptional

Allowed values:

subjectstringOptional<=500 characters

timezonestring or nullOptional<=64 characters

Response

Created conversation

agentModestring

createdAtstring

externalParticipantIdstring or null

externalThreadIdstring or null

idstring

lastMessageAtstring or null

messageCountdouble

participantEmailstring or null

participantNamestring or null

statusstring

subjectstring or null

surfaceIdstring

takeoverActorIdstring or null

takeoverActorTypestring or null

takeoverAtstring or null

takeoverReasonstring or null

timezonestring or null

updatedAtstring

contextmap from strings to any

participantMetadatamap from strings to any

surfaceobject

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error