Create conversation with the Chatwoot API
Starts a conversation with a contact in an inbox, optionally with a first message. source_id identifies the contact in that inbox: it comes from contact_inboxes of Search contacts, from Create contact or from Create contact inbox. On WhatsApp inboxes, the first message goes as an approved template in message.template_params.
- Identifier
- chatwoot_create_conversation
The request
POST https://connect.reportei.com/api/tools/chatwoot_create_conversation/execute
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Content-Type: application/json
Accept: application/json
{
"customer_toolkit": "<connection UUID>",
"arguments": {
"account_id": 1,
"source_id": "<source_id>"
}
}Your system sends your customer's connection id and the tool arguments. The headers are the same as the rest of the Connect API: your product's token and your customer's token.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| account_id | integer | Yes | Id of the Chatwoot account: the id of one of the accounts from Get profile, also shown in the dashboard URL after /accounts/, as in app.chatwoot.com/app/accounts/123. |
| source_id | string | Yes | source_id of the contact in the inbox, from contact_inboxes of Search contacts, Create contact or Create contact inbox. Each item pairs an inbox with its source_id. |
| inbox_id | integer | No | Inbox of the conversation, the same of the source_id, from List inboxes. |
| contact_id | integer | No | Id of the contact, from Search contacts. |
| status | string | No | Initial status of the conversation.Values: open, resolved, pending |
| assignee_id | integer | No | Id of the agent to assign, from List agents. |
| team_id | integer | No | Id of the team to assign, from List teams. |
| custom_attributes | object | No | Conversation custom attribute values keyed by attribute key. |
| message | object | No | First message of the conversation, sent to the contact. |
Supported connections
Your customer connects their Chatwoot account once, with one of the modes below. The same connection serves every tool of the toolkit.
API key
Your customer pastes the app's key on a Connect screen, or your system sends the key with POST /api/customer-toolkits, with no screen.
The response
On success, Connect preserves the app's response status and body. HTTP errors returned by the app use the {error, api_error} envelope; authentication or validation can fail before execution. The X-Toolkit-Execution-Id header identifies the recorded execution, available at GET /api/tools/executions/{uuid}.
Ready for AI agents
This tool's input is a JSON Schema, available at GET /api/tools/chatwoot_create_conversation. It becomes your agent's tool definition with no conversion.
Other Chatwoot tools
- List conversationsGETLists conversations of an account, the open ones by default, with status, labels, inbox_id, can_reply, the contact in meta.sender, the assignee and the last message. data.meta has the counts by assignee type. Pages are numbered from 1; an empty payload means there are no more pages.
- Update conversation statusPOSTSets the status of a conversation: open, resolved, pending or snoozed. Without snoozed_until a snoozed conversation waits for the next reply of the contact, and any reply of the contact reopens it.
- Assign conversationPOSTAssigns a conversation to an agent or to a team. When assignee_id is sent, team_id is ignored.
- Update conversation labelsPOSTSets the labels of a conversation. The list sent replaces the current labels, so it must include the ones to keep.
- List messagesGETReturns the latest messages of a conversation in ascending order, with meta holding its labels, contact and assignee. sender_type says who sent each message, and private marks internal notes. For older messages, pass before with the id of the oldest one received.
- Create messagePOSTSends a message in a conversation. An outgoing message goes to the contact through the channel of the inbox, such as WhatsApp, email or the website widget; private true makes it an internal note only agents see. On WhatsApp, template_params sends an approved template.
- Search contactsGETSearches the contacts that have an identifier, email or phone, by name, identifier, email or phone number, 15 per page. Each contact has contact_inboxes, pairing each inbox with the source_id that Create conversation needs. meta.count is the total; a page with fewer than 15 contacts is the last one.
- Create contactPOSTCreates a contact in an inbox of the account. The response brings the contact and the contact_inbox with the source_id that Create conversation needs.
Toolkits in the same category
See all 100 toolkitsSee Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
