Skip to main content
POST
/
api
/
agents
/
{agentId}
/
conversations
Start a new conversation with an agent
curl --request POST \
  --url http://localhost:3000/api/agents/{agentId}/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": "<string>",
  "contactId": "<string>",
  "title": "Support inquiry about refund"
}
'
{
  "id": "<string>",
  "organizationId": "<string>",
  "agentId": "<string>",
  "mastraThreadId": "<string>",
  "messageCount": 123,
  "status": "pending",
  "startedAt": "2023-11-07T05:31:56Z",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "userId": "<string>",
  "contactId": "<string>",
  "title": "<string>",
  "lastMessageAt": "<string>",
  "endedAt": "<string>"
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

agentId
string
required

Agent ID

Body

application/json
userId
string

User ID (for internal users)

contactId
string

Contact ID (for external contacts)

title
string

Conversation title

Maximum string length: 255
Example:

"Support inquiry about refund"

Response

Conversation started successfully

id
string
required

Conversation ID

organizationId
string
required

Organization ID

agentId
string
required

Agent ID

mastraThreadId
string
required

Mastra thread ID

messageCount
number
required

Message count

status
enum<string>
required

Conversation status

Available options:
pending,
active,
ended,
failed,
archived
startedAt
string<date-time>
required

Started at timestamp

createdAt
string<date-time>
required

Created at timestamp

updatedAt
string<date-time>
required

Updated at timestamp

userId
string | null

User ID

contactId
string | null

Contact ID

title
string | null

Conversation title

lastMessageAt
string | null

Last message timestamp

endedAt
string | null

Ended at timestamp