Starting a conversation with an Agent
Starts a new conversation between a visitor and a live agent.
Every field is optional. Send user when you know who the visitor is: an email links the conversation to
the person the agent has already talked to with that email, and any name or phone_number you send
updates what is stored. Without an email, a new visitor is created every time.
The response includes the visitor as a participant with their token, which sends and lists messages in
every conversation they take part in. Tokens last 90 days (token_expires_at). A visitor matched by email
keeps the token they already have, unless it expires within 7 days: then they get a new one for another 90
days.
apiKeyAuthorizationBearer <token>Your Dispatch API key, sent as Authorization: Bearer <key>. Used to start and get conversations. The key
is visible in your website's source, so it only allows starting conversations with the agents you chose.
agent*stringThe agent's ID. It is in the agent's address in Dispatch (https://app.rundispatch.ai/agents/<id>) and in
the agent's Channels dialog, which can copy it.
uuidapplication/json- body
user?Who the visitor is. Every field is optional.
context?array<>What the agent should know for the whole conversation. Dispatch adds the visitor's name, email and phone number in front of these.
items <= 17The conversation was started.
application/json- response
data*curl -X POST 'https://api.rundispatch.ai/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/conversations' \ -H 'Content-Type: application/json' \ -d '{ "user": { "name": "Jane", "email": "jane@example.com", "phone_number": "+639171234567" }, "context": [ { "label": "Page", "description": "Page the visitor is on", "value": "/pricing" } ]}'{ "data": { "id": "0199d2f4-0a1b-7c2d-8e3f-405162738495", "agent": { "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b", "name": "Ava", "title": "Support Agent" }, "context": [ { "label": "Name", "description": "The visitor's name", "value": "Jane" }, { "label": "Page", "description": "Page the visitor is on", "value": "/pricing" } ], "created_at": "2026-10-13T08:00:00+00:00", "_links": { "self": { "href": "https://api.rundispatch.ai/v1/conversations/0199d2f4-0a1b-7c2d-8e3f-405162738495" }, "list_messages": { "href": "https://api.rundispatch.ai/v1/conversations/0199d2f4-0a1b-7c2d-8e3f-405162738495/messages" }, "send_message": { "href": "https://api.rundispatch.ai/v1/conversations/0199d2f4-0a1b-7c2d-8e3f-405162738495/messages" } }, "_embedded": { "participants": [ { "id": "0199e4a0-5b6c-7d8e-9f01-23456789abcd", "type": "end_user", "name": "Jane", "email": "jane@example.com", "phone_number": "+639171234567", "token": "8d1kQ2vX7bN4mR9tY3wZ6pL0sH5jF2cA", "token_expires_at": "2027-01-11T08:00:00+00:00" } ] } }}