Skip to main content
The REST API reads and changes one workspace: its agents, conversations and messages, contacts, leads and knowledge. You can also send a customer’s message to an agent and get its reply, without the chat widget. Every endpoint is on every plan.
The API reference tab lists every endpoint with its parameters and responses, and lets you try each one. It starts with authentication and the conventions every endpoint follows: errors, pagination and rate limits. It is built from an OpenAPI 3.1 spec you can also import into Postman or a code generator: https://wiredesk.ai/docs/api-reference/openapi.json. The same operations are also tools on the MCP server, for AI assistants. This page covers what the reference leaves out: how changing an agent, talking to one, search, knowledge and contacts behave.

​
Change an agent

PATCH /agents/{agent_id} changes the agent’s name (up to 80 characters), greeting (300) or instructions (4,000). Send only the fields that change. They take effect on every channel at once. greeting is the phone greeting, spoken when the agent picks up a call; website chat opens with the widget’s own opening message instead. Each change is a new version in the agent’s Settings › Version history, so you can roll it back, and appears in the activity log with the key’s name. Voice, actions, channels and the widget’s look are changed in the dashboard.

​
Talk to an agent

POST /agents/{agent_id}/chat runs the same agent as the chat widget, with the same instructions, knowledge, actions and handover. It is billed as a chat reply.
  • Leave out conversation_id to start a conversation. Pass the one you got back to continue it. Only conversations started through the API can be continued this way.
  • user_id is your own id for the person. Their conversations then share one contact, of kind api, whose value is your user_id. It is kept apart from website visitors, so nobody on your website can claim it. Without it, each conversation gets a contact of its own.
  • name is stored on the contact if it has none yet.
  • If a teammate has taken the conversation over, reply is null and handover_state is active. Their reply arrives in the messages list and as a message.created webhook.
  • If the agent asked for a person during its reply, handover_state is requested.
  • If the workspace is at its spend cap, the request gets 402 and nothing is stored.
  • If the agent’s chat channel is switched off, the request gets 403 and nothing is stored.
API conversations appear in Conversations with the channel Website chat.

​
Search conversations

GET /conversations/search?q= finds what the search box on the Conversations page finds: the customer’s name, number or email, the agent, the channel, the summary, the topic and the outcome. The match is case-insensitive. One request reads at most 1,000 conversations, newest first. If it stops there without filling the page, has_more is true and next_cursor continues from where it stopped, even if data is empty. Keep following the cursor until has_more is false.

​
Knowledge

  • Text ("type": "text", with content up to 200,000 characters and an optional label) is indexed before the response. It comes back 201 with status: "ready".
  • A website ("type": "url", with url) is crawled in the background. It comes back 202 with status: "pending". List the sources to see when it is ready or error.
  • Files are not in the API yet. Upload them on the agent’s Knowledge page.
  • Q&A answers (qa) and synced sources (zendesk_guide, intercom_articles, notion, confluence) appear in the list and can be deleted here, but are added on the agent’s Knowledge page. Deleting a synced source removes every article it brought in.
  • GET /agents/{agent_id}/knowledge/search?q= returns the passages the agent itself would find, best first, each with its source and score.

​
Contacts

You can add a contact before they ever get in touch, for example from your CRM, so the agents know their name. kind is phone (in international format, like +14155550123) or email. The first call or email from that number or address lands on that contact. Website visitors’ contacts are created by their conversations and cannot be made by hand. Deleting a contact also deletes the notes the agents saved about them (“Remember callers”). Their conversations stay.