{
    "info": {
        "name": "Dispatch API",
        "description": "The Dispatch API lets your website start conversations with a live agent and exchange messages with it.\nEvery response is JSON except a reply to a message, which can also be Server-Sent Events, Markdown or plain text.\n\nSet `apiKey` (and `agent`) in the collection's variables, then run *Starting a conversation with an Agent*. It saves the conversation and the visitor's token for the other requests.\n\nDocs: https://docs.rundispatch.ai",
        "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
    },
    "item": [
        {
            "name": "Conversations",
            "description": "Start a conversation with an agent, then send and list its messages.",
            "item": [
                {
                    "name": "Starting a conversation with an Agent",
                    "event": [
                        {
                            "listen": "test",
                            "script": {
                                "type": "text/javascript",
                                "exec": [
                                    "if (pm.response.code < 300) {",
                                    "    const { data } = pm.response.json();",
                                    "    const participant = data._embedded.participants[0];",
                                    "    pm.collectionVariables.set('conversation', data.id);",
                                    "    pm.collectionVariables.set('participantToken', participant.token);",
                                    "}"
                                ]
                            }
                        }
                    ],
                    "request": {
                        "method": "POST",
                        "auth": {
                            "type": "bearer",
                            "bearer": [
                                {
                                    "key": "token",
                                    "value": "{{apiKey}}",
                                    "type": "string"
                                }
                            ]
                        },
                        "header": [
                            {
                                "key": "Accept",
                                "value": "application/json"
                            },
                            {
                                "key": "Content-Type",
                                "value": "application/json"
                            }
                        ],
                        "body": {
                            "mode": "raw",
                            "raw": "{\n    \"user\": {\n        \"name\": \"Jane\",\n        \"email\": \"jane@example.com\",\n        \"phone_number\": \"+639171234567\"\n    },\n    \"context\": [\n        {\n            \"label\": \"Page\",\n            \"description\": \"Page the visitor is on\",\n            \"value\": \"/pricing\"\n        }\n    ]\n}",
                            "options": {
                                "raw": {
                                    "language": "json"
                                }
                            }
                        },
                        "url": {
                            "raw": "{{baseUrl}}/agents/:agent/conversations",
                            "host": [
                                "{{baseUrl}}"
                            ],
                            "path": [
                                "agents",
                                ":agent",
                                "conversations"
                            ],
                            "variable": [
                                {
                                    "key": "agent",
                                    "value": "{{agent}}",
                                    "description": "The agent's ID. It is in the agent's address in Dispatch (`https://app.rundispatch.ai/agents/<id>`) and in\nthe agent's Channels dialog, which can copy it."
                                }
                            ],
                            "query": []
                        },
                        "description": "Starts a new conversation between a visitor and a live agent.\n\nEvery field is optional. Send `user` when you know who the visitor is: an `email` links the conversation to\nthe person the agent has already talked to with that email, and any `name` or `phone_number` you send\nupdates what is stored. Without an `email`, a new visitor is created every time.\n\nThe response includes the visitor as a participant with their `token`, which sends and lists messages in\nevery conversation they take part in. Tokens last 90 days (`token_expires_at`). A visitor matched by `email`\nkeeps the token they already have, unless it expires within 7 days: then they get a new one for another 90\ndays."
                    },
                    "response": [
                        {
                            "name": "The conversation was started.",
                            "originalRequest": {
                                "method": "POST",
                                "header": [],
                                "url": {
                                    "raw": "{{baseUrl}}/agents/:agent/conversations",
                                    "host": [
                                        "{{baseUrl}}"
                                    ],
                                    "path": [
                                        "agents",
                                        ":agent",
                                        "conversations"
                                    ],
                                    "variable": [
                                        {
                                            "key": "agent",
                                            "value": "{{agent}}",
                                            "description": "The agent's ID. It is in the agent's address in Dispatch (`https://app.rundispatch.ai/agents/<id>`) and in\nthe agent's Channels dialog, which can copy it."
                                        }
                                    ],
                                    "query": []
                                }
                            },
                            "status": "The conversation was started.",
                            "code": 201,
                            "_postman_previewlanguage": "json",
                            "header": [
                                {
                                    "key": "Content-Type",
                                    "value": "application/json"
                                }
                            ],
                            "body": "{\n    \"data\": {\n        \"id\": \"0199d2f4-0a1b-7c2d-8e3f-405162738495\",\n        \"agent\": {\n            \"id\": \"0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b\",\n            \"name\": \"Ava\",\n            \"title\": \"Support Agent\"\n        },\n        \"context\": [\n            {\n                \"label\": \"Name\",\n                \"description\": \"The visitor's name\",\n                \"value\": \"Jane\"\n            },\n            {\n                \"label\": \"Page\",\n                \"description\": \"Page the visitor is on\",\n                \"value\": \"/pricing\"\n            }\n        ],\n        \"created_at\": \"2026-10-13T08:00:00+00:00\",\n        \"_links\": {\n            \"self\": {\n                \"href\": \"https://api.rundispatch.ai/v1/conversations/0199d2f4-0a1b-7c2d-8e3f-405162738495\"\n            },\n            \"list_messages\": {\n                \"href\": \"https://api.rundispatch.ai/v1/conversations/0199d2f4-0a1b-7c2d-8e3f-405162738495/messages\"\n            },\n            \"send_message\": {\n                \"href\": \"https://api.rundispatch.ai/v1/conversations/0199d2f4-0a1b-7c2d-8e3f-405162738495/messages\"\n            }\n        },\n        \"_embedded\": {\n            \"participants\": [\n                {\n                    \"id\": \"0199e4a0-5b6c-7d8e-9f01-23456789abcd\",\n                    \"type\": \"end_user\",\n                    \"name\": \"Jane\",\n                    \"email\": \"jane@example.com\",\n                    \"phone_number\": \"+639171234567\",\n                    \"token\": \"8d1kQ2vX7bN4mR9tY3wZ6pL0sH5jF2cA\",\n                    \"token_expires_at\": \"2027-01-11T08:00:00+00:00\"\n                }\n            ]\n        }\n    }\n}"
                        }
                    ]
                },
                {
                    "name": "Getting a conversation",
                    "event": [
                        {
                            "listen": "test",
                            "script": {
                                "type": "text/javascript",
                                "exec": [
                                    "if (pm.response.code < 300) {",
                                    "    const { data } = pm.response.json();",
                                    "    const participant = data._embedded.participants[0];",
                                    "    pm.collectionVariables.set('conversation', data.id);",
                                    "    pm.collectionVariables.set('participantToken', participant.token);",
                                    "}"
                                ]
                            }
                        }
                    ],
                    "request": {
                        "method": "GET",
                        "auth": {
                            "type": "bearer",
                            "bearer": [
                                {
                                    "key": "token",
                                    "value": "{{apiKey}}",
                                    "type": "string"
                                }
                            ]
                        },
                        "header": [
                            {
                                "key": "Accept",
                                "value": "application/json"
                            }
                        ],
                        "url": {
                            "raw": "{{baseUrl}}/conversations/:conversation",
                            "host": [
                                "{{baseUrl}}"
                            ],
                            "path": [
                                "conversations",
                                ":conversation"
                            ],
                            "variable": [
                                {
                                    "key": "conversation",
                                    "value": "{{conversation}}",
                                    "description": "The conversation's `id`."
                                }
                            ],
                            "query": []
                        },
                        "description": "Returns a conversation with its participants, including each participant's `token`. Use it to resume a\nconversation or to recover a token you lost. A token in its last 7 days, or already expired, is replaced by a new\none valid for another 90 days.\n\nOnly the API key that started the conversation can get it. Any other key gets `404`."
                    },
                    "response": [
                        {
                            "name": "The conversation.",
                            "originalRequest": {
                                "method": "GET",
                                "header": [],
                                "url": {
                                    "raw": "{{baseUrl}}/conversations/:conversation",
                                    "host": [
                                        "{{baseUrl}}"
                                    ],
                                    "path": [
                                        "conversations",
                                        ":conversation"
                                    ],
                                    "variable": [
                                        {
                                            "key": "conversation",
                                            "value": "{{conversation}}",
                                            "description": "The conversation's `id`."
                                        }
                                    ],
                                    "query": []
                                }
                            },
                            "status": "The conversation.",
                            "code": 200,
                            "_postman_previewlanguage": "json",
                            "header": [
                                {
                                    "key": "Content-Type",
                                    "value": "application/json"
                                }
                            ],
                            "body": "{\n    \"data\": {\n        \"id\": \"0199d2f4-0a1b-7c2d-8e3f-405162738495\",\n        \"agent\": {\n            \"id\": \"0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b\",\n            \"name\": \"Ava\",\n            \"title\": \"Support Agent\"\n        },\n        \"context\": [\n            {\n                \"label\": \"Name\",\n                \"description\": \"The visitor's name\",\n                \"value\": \"Jane\"\n            },\n            {\n                \"label\": \"Page\",\n                \"description\": \"Page the visitor is on\",\n                \"value\": \"/pricing\"\n            }\n        ],\n        \"created_at\": \"2026-10-13T08:00:00+00:00\",\n        \"_links\": {\n            \"self\": {\n                \"href\": \"https://api.rundispatch.ai/v1/conversations/0199d2f4-0a1b-7c2d-8e3f-405162738495\"\n            },\n            \"list_messages\": {\n                \"href\": \"https://api.rundispatch.ai/v1/conversations/0199d2f4-0a1b-7c2d-8e3f-405162738495/messages\"\n            },\n            \"send_message\": {\n                \"href\": \"https://api.rundispatch.ai/v1/conversations/0199d2f4-0a1b-7c2d-8e3f-405162738495/messages\"\n            }\n        },\n        \"_embedded\": {\n            \"participants\": [\n                {\n                    \"id\": \"0199e4a0-5b6c-7d8e-9f01-23456789abcd\",\n                    \"type\": \"end_user\",\n                    \"name\": \"Jane\",\n                    \"email\": \"jane@example.com\",\n                    \"phone_number\": \"+639171234567\",\n                    \"token\": \"8d1kQ2vX7bN4mR9tY3wZ6pL0sH5jF2cA\",\n                    \"token_expires_at\": \"2027-01-11T08:00:00+00:00\"\n                }\n            ]\n        }\n    }\n}"
                        }
                    ]
                },
                {
                    "name": "Listing a conversation's messages",
                    "request": {
                        "method": "GET",
                        "auth": {
                            "type": "bearer",
                            "bearer": [
                                {
                                    "key": "token",
                                    "value": "{{participantToken}}",
                                    "type": "string"
                                }
                            ]
                        },
                        "header": [
                            {
                                "key": "Accept",
                                "value": "application/json"
                            }
                        ],
                        "url": {
                            "raw": "{{baseUrl}}/conversations/:conversation/messages",
                            "host": [
                                "{{baseUrl}}"
                            ],
                            "path": [
                                "conversations",
                                ":conversation",
                                "messages"
                            ],
                            "variable": [
                                {
                                    "key": "conversation",
                                    "value": "{{conversation}}",
                                    "description": "The conversation's `id`."
                                }
                            ],
                            "query": [
                                {
                                    "key": "per_page",
                                    "value": "20",
                                    "description": "How many messages to return.",
                                    "disabled": true
                                },
                                {
                                    "key": "cursor",
                                    "value": "",
                                    "description": "The cursor of the page to load. Take it from `links.next`/`links.prev` or `meta.next_cursor`.",
                                    "disabled": true
                                }
                            ]
                        },
                        "description": "Lists the conversation's messages, **newest first**, with cursor pagination. Load the first page to show\nthe latest messages, then follow `links.next` for older ones.\n\nAuthenticate with the participant's `token`, not the API key. A token of a visitor outside the conversation\ngets `403`.\n\nOnly what the visitor sees is listed: the visitor's messages, the agent's replies and files the agent\nshared. A file that no longer exists keeps its place with `url` set to `null`. File URLs are signed and stop\nworking at `expires_at`; list the messages again to get new ones.\n\nWhen a scheduled task runs, it runs in a child conversation, and the parent conversation gets a message of\ntype `conversation` pointing to it through `conversation_id`. List the child's messages with this same\nendpoint and the same token. A child conversation is a record of the run, so sending a message to it fails\nwith `422`."
                    },
                    "response": [
                        {
                            "name": "A page of messages, newest first.",
                            "originalRequest": {
                                "method": "GET",
                                "header": [],
                                "url": {
                                    "raw": "{{baseUrl}}/conversations/:conversation/messages",
                                    "host": [
                                        "{{baseUrl}}"
                                    ],
                                    "path": [
                                        "conversations",
                                        ":conversation",
                                        "messages"
                                    ],
                                    "variable": [
                                        {
                                            "key": "conversation",
                                            "value": "{{conversation}}",
                                            "description": "The conversation's `id`."
                                        }
                                    ],
                                    "query": [
                                        {
                                            "key": "per_page",
                                            "value": "20",
                                            "description": "How many messages to return.",
                                            "disabled": true
                                        },
                                        {
                                            "key": "cursor",
                                            "value": "",
                                            "description": "The cursor of the page to load. Take it from `links.next`/`links.prev` or `meta.next_cursor`.",
                                            "disabled": true
                                        }
                                    ]
                                }
                            },
                            "status": "A page of messages, newest first.",
                            "code": 200,
                            "_postman_previewlanguage": "json",
                            "header": [
                                {
                                    "key": "Content-Type",
                                    "value": "application/json"
                                }
                            ],
                            "body": "{\n    \"data\": [\n        {\n            \"id\": \"0199d2f4-1c4e-7a1b-9e0e-3b1f5c6d7e80\",\n            \"role\": \"agent\",\n            \"type\": \"file\",\n            \"content\": \"\",\n            \"file\": {\n                \"name\": \"menu.pdf\",\n                \"mime_type\": \"application/pdf\",\n                \"url\": \"https://files.rundispatch.ai/menu.pdf?signature=4f9c2e7a\",\n                \"preview_url\": null,\n                \"download_url\": \"https://files.rundispatch.ai/menu.pdf?download=1&signature=4f9c2e7a\",\n                \"expires_at\": \"2026-10-13T09:00:00+00:00\"\n            },\n            \"failed\": false,\n            \"created_at\": \"2026-10-13T08:00:05+00:00\"\n        },\n        {\n            \"id\": \"0199d2f4-1a2b-7c3d-8e4f-5a6b7c8d9e0f\",\n            \"role\": \"agent\",\n            \"type\": \"text\",\n            \"content\": \"Here's our menu.\",\n            \"failed\": false,\n            \"citations\": [\n                {\n                    \"url\": \"https://docs.example.com/menu\",\n                    \"title\": \"Our menu\"\n                }\n            ],\n            \"created_at\": \"2026-10-13T08:00:04+00:00\"\n        },\n        {\n            \"id\": \"0199d2f4-0f1e-7d2c-9b3a-4c5d6e7f8091\",\n            \"role\": \"user\",\n            \"type\": \"text\",\n            \"participant_id\": \"0199e4a0-5b6c-7d8e-9f01-23456789abcd\",\n            \"content\": \"Show me the menu\",\n            \"context\": [\n                {\n                    \"label\": \"Page\",\n                    \"description\": \"Page the visitor is on\",\n                    \"value\": \"/menu\"\n                }\n            ],\n            \"created_at\": \"2026-10-13T08:00:00+00:00\"\n        }\n    ],\n    \"links\": {\n        \"first\": null,\n        \"last\": null,\n        \"prev\": null,\n        \"next\": \"https://api.rundispatch.ai/v1/conversations/0199d2f4-0a1b-7c2d-8e3f-405162738495/messages?cursor=eyJpZCI6MX0\"\n    },\n    \"meta\": {\n        \"path\": \"https://api.rundispatch.ai/v1/conversations/0199d2f4-0a1b-7c2d-8e3f-405162738495/messages\",\n        \"per_page\": 20,\n        \"next_cursor\": \"eyJpZCI6MX0\",\n        \"prev_cursor\": null\n    }\n}"
                        }
                    ]
                },
                {
                    "name": "Sending a message to an Agent",
                    "request": {
                        "method": "POST",
                        "auth": {
                            "type": "bearer",
                            "bearer": [
                                {
                                    "key": "token",
                                    "value": "{{participantToken}}",
                                    "type": "string"
                                }
                            ]
                        },
                        "header": [
                            {
                                "key": "Accept",
                                "value": "application/json"
                            },
                            {
                                "key": "Content-Type",
                                "value": "application/json"
                            }
                        ],
                        "body": {
                            "mode": "raw",
                            "raw": "{\n    \"content\": \"How do I go back home from this page?\",\n    \"context\": [\n        {\n            \"label\": \"Page\",\n            \"description\": \"Page the visitor is on\",\n            \"value\": \"/checkout/step-2\"\n        },\n        {\n            \"label\": \"Local time\",\n            \"description\": \"Visitor's local time\",\n            \"value\": \"2026-10-13T16:02:00+08:00 (Asia/Manila)\"\n        }\n    ]\n}",
                            "options": {
                                "raw": {
                                    "language": "json"
                                }
                            }
                        },
                        "url": {
                            "raw": "{{baseUrl}}/conversations/:conversation/messages",
                            "host": [
                                "{{baseUrl}}"
                            ],
                            "path": [
                                "conversations",
                                ":conversation",
                                "messages"
                            ],
                            "variable": [
                                {
                                    "key": "conversation",
                                    "value": "{{conversation}}",
                                    "description": "The conversation's `id`."
                                }
                            ],
                            "query": []
                        },
                        "description": "Sends the visitor's message and returns the agent's reply. The `Accept` header picks how the reply comes\nback:\n\n| `Accept` | Reply |\n| --- | --- |\n| `application/json` (or none) | All at once, as JSON: the Markdown and the files the agent shared. |\n| `text/event-stream` | Streamed as it is written. See *Streaming* below. |\n| `text/markdown` | All at once, as Markdown. Shared files appear as images or links where they were written. |\n| `text/plain` | All at once, as plain text without Markdown, for places such as SMS. The agent shares no files. |\n\nAny other type returns `406`.\n\nAuthenticate with the participant's `token`. The message is sent as that participant, who must take part in\nthe conversation; anyone else gets `403`.\n\n### Streaming\n\nThe reply is a stream of `data:` lines, each holding one JSON event, and ends with `data: [DONE]`. Append\nthe `delta` of every `text_delta` event to show the reply as it is written. An `embed_file` event is a file\nthe agent shared. Ignore event types you don't use; new ones may be added.\n\n```\ndata: {\"type\":\"stream_start\", …}\ndata: {\"type\":\"text_start\",\"message_id\":\"…\", …}\ndata: {\"type\":\"text_delta\",\"message_id\":\"…\",\"delta\":\"Here's \", …}\ndata: {\"type\":\"text_delta\",\"message_id\":\"…\",\"delta\":\"our menu.\", …}\ndata: {\"type\":\"embed_file\",\"name\":\"menu.pdf\",\"mime_type\":\"application/pdf\",\"url\":\"…\", …}\ndata: {\"type\":\"stream_end\",\"reason\":\"stop\", …}\ndata: [DONE]\n```\n\nReplies as JSON. To get the reply another way, change the `Accept` header to `text/event-stream`, `text/markdown` or `text/plain`."
                    },
                    "response": [
                        {
                            "name": "The agent's reply.",
                            "originalRequest": {
                                "method": "POST",
                                "header": [],
                                "url": {
                                    "raw": "{{baseUrl}}/conversations/:conversation/messages",
                                    "host": [
                                        "{{baseUrl}}"
                                    ],
                                    "path": [
                                        "conversations",
                                        ":conversation",
                                        "messages"
                                    ],
                                    "variable": [
                                        {
                                            "key": "conversation",
                                            "value": "{{conversation}}",
                                            "description": "The conversation's `id`."
                                        }
                                    ],
                                    "query": []
                                }
                            },
                            "status": "The agent's reply.",
                            "code": 200,
                            "_postman_previewlanguage": "json",
                            "header": [
                                {
                                    "key": "Content-Type",
                                    "value": "application/json"
                                }
                            ],
                            "body": "{\n    \"data\": {\n        \"markdown\": \"Here's our menu.\\n\\n[menu.pdf](https://files.rundispatch.ai/menu.pdf?signature=4f9c2e7a)\",\n        \"attachments\": [\n            {\n                \"id\": \"0199c1a2-3b4c-7d5e-8f60-718293a4b5c6\",\n                \"type\": \"file\",\n                \"name\": \"menu.pdf\",\n                \"mime_type\": \"application/pdf\",\n                \"url\": \"https://files.rundispatch.ai/menu.pdf?signature=4f9c2e7a\",\n                \"preview_url\": null,\n                \"download_url\": \"https://files.rundispatch.ai/menu.pdf?download=1&signature=4f9c2e7a\",\n                \"expires_at\": \"2026-10-13T09:00:00+00:00\"\n            }\n        ]\n    }\n}"
                        }
                    ]
                }
            ]
        }
    ],
    "variable": [
        {
            "key": "baseUrl",
            "value": "https://api.rundispatch.ai/v1",
            "description": "The API base URL."
        },
        {
            "key": "apiKey",
            "value": "",
            "description": "Your Dispatch API key."
        },
        {
            "key": "agent",
            "value": "",
            "description": "The agent's ID."
        },
        {
            "key": "conversation",
            "value": "",
            "description": "Saved by starting or getting a conversation."
        },
        {
            "key": "participantToken",
            "value": "",
            "description": "The visitor's token. Saved by starting or getting a conversation."
        }
    ]
}