- Docs
- Developers
REST API
Read and change your TalkingDot workspace from your own servers: sync contacts, record events, start and answer conversations, work with tickets, and manage help-center articles.
Overview
The REST API is organised around resources (contacts, conversations, articles and so on), uses standard HTTP methods and status codes, and accepts and returns JSON. Every request is scoped to the workspace that owns the API key.
| Base URL | https://talkingdot.com/api/v1 |
|---|---|
| Authentication | Authorization: Bearer <api key> |
| Format | JSON request bodies and JSON responses |
| IDs | Integers |
| Timestamps | ISO 8601 in UTC, for example 2026-10-03T09:15:00Z |
| Rate limit | 120 requests per minute per API key |
Try it with your key:
curl https://talkingdot.com/api/v1/me \
-H "Authorization: Bearer cn_live_xxxxxxxx"Authentication
Authenticate every request with an API key in the Authorization header, as a bearer token. Workspace admins create keys in Settings → Developers → API keys. Keys look like cn_live_xxxxxxxx and belong to one workspace.
curl https://talkingdot.com/api/v1/contacts \
-H "Authorization: Bearer cn_live_xxxxxxxx"When you create a key, choose its access: Read and write (everything below) or Read only. A read-only key can make GET requests and subscribe to webhooks (they send only what the key can read anyway); anything else gets a 403 with the error code forbidden. The same keys work with the MCP server for AI apps.
A request with a missing, invalid or revoked key gets a 401 response with the error code unauthorized. A key works while the teammate who created it is on the team: when they leave or are removed it stops for good (401). It is paused (403, code forbidden) while their account is suspended, and while they are no longer an owner or admin of the workspace (for example after being made an agent); it works again when that changes. While a key is paused, the webhook subscriptions it made get no events. An owner or admin of the workspace can create a new key at any time.
Keep API keys secret. A key can read and change your whole workspace, including contacts' personal data. Use it only from your servers: never in browser JavaScript, mobile apps or public repositories. Copy a new key when it's created, because only a hash of it is stored. If a key leaks, revoke it in Settings → Developers → API keys and create a new one.
Requests and responses
Send request bodies as JSON with a Content-Type: application/json header. Every response is JSON.
A successful response has a 2xx status (for example 201 Created for a new contact) and wraps the result in data. For a single object, data is that object:
{
"data": {
"id": 1842,
"name": "Ada Lovelace",
"email": "ada@example.com"
}
}For lists, data is an array and meta holds the pagination cursor:
{
"data": [
{ "id": 1842, "name": "Ada Lovelace", "email": "ada@example.com" }
],
"meta": {
"next_cursor": "1842"
}
}These two snippets are shortened; real objects contain every field listed in the object reference. Fields without a value are null, never left out.
Pagination
List endpoints return results a page at a time. Control the page with two query parameters:
| Parameter | Type | Description |
|---|---|---|
limit | integer | How many results to return, from 1 to 100. Default 25. |
cursor | string | The meta.next_cursor value from the previous page. Leave it out for the first page. |
Keep requesting with the latest next_cursor until it comes back as null. Treat cursors as opaque strings: don't build or change them yourself. A limit outside 1 to 100, a cursor that isn't one we gave you, or an unknown filter value (such as type=bogus) gets a 422; nothing is changed or ignored quietly.
curl "https://talkingdot.com/api/v1/conversations?status=open&limit=100" \
-H "Authorization: Bearer cn_live_xxxxxxxx"
curl "https://talkingdot.com/api/v1/conversations?status=open&limit=100&cursor=5431" \
-H "Authorization: Bearer cn_live_xxxxxxxx"The same loop in Node.js 18+:
async function listAllOpenConversations() {
const results = [];
let cursor = null;
do {
const url = new URL('https://talkingdot.com/api/v1/conversations');
url.searchParams.set('status', 'open');
url.searchParams.set('limit', '100');
if (cursor) url.searchParams.set('cursor', cursor);
const res = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.TALKINGDOT_API_KEY}` },
});
if (!res.ok) throw new Error(`API request failed with HTTP ${res.status}`);
const body = await res.json();
results.push(...body.data);
cursor = body.meta.next_cursor;
} while (cursor);
return results;
}Errors
Failed requests return a 4xx status and an error object. Branch on code; message is a human-readable explanation that may change.
{
"error": {
"code": "not_found",
"message": "Contact not found."
}
}| HTTP status | code | Meaning |
|---|---|---|
400 | invalid_json | The request body isn't a JSON object (broken JSON, or a list instead of an object). |
401 | unauthorized | The API key is missing, invalid or revoked — also when the teammate who created it is no longer on the team. |
402 | payment_required | The conversation came in after the Free plan's monthly limit: replies to it are refused until the workspace is upgraded. |
403 | forbidden | The key is valid but isn't allowed to make this request — a read-only key trying to make a change, or while the workspace, or the account of the teammate who created the key, is suspended, or while that teammate is no longer an owner or admin. |
404 | not_found | The object doesn't exist in this workspace, or the endpoint doesn't exist. |
405 | method_not_allowed | The endpoint exists but doesn't take this HTTP method. The Allow header lists the ones it takes. |
409 | conflict | Another contact already has this external_id (when you create or update a contact). |
422 | validation | The request body or a query parameter is invalid, for example a malformed email, a value of the wrong type or an unknown status. Nothing is changed. message says what to fix. |
429 | rate_limited | Too many requests. Wait for the number of seconds in the Retry-After header, then try again. |
Rate limits
Each API key can make 120 requests per minute. Every response tells you where you stand:
| Header | Description |
|---|---|
X-RateLimit-Limit | Requests allowed per minute for this key (120). |
X-RateLimit-Remaining | Requests left in the current minute. |
Retry-After | Sent with a 429 response: seconds to wait before retrying (until the current minute's count starts again). |
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 17
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
{"error": {"code": "rate_limited", "message": "Too many requests."}}For bulk jobs such as a contact import, keep an eye on X-RateLimit-Remaining and pause when it reaches 0, rather than waiting for a 429.
Me
/api/v1/meReturns details of the workspace your API key belongs to. Use it to check that a key works before you use it for anything else.
curl https://talkingdot.com/api/v1/me \
-H "Authorization: Bearer cn_live_xxxxxxxx"{
"data": {
"workspace": {
"id": 12,
"name": "Acme",
"public_key": "a1b2c3d4e5f6a7b8",
"website_url": "https://www.example.com",
"timezone": "Europe/London"
},
"key": {
"name": "CRM sync",
"prefix": "cn_live_Ab3dE6"
}
}
}public_key is the workspace key the messenger uses (it's public, not a secret). prefix is the start of the API key, as shown in Settings → Developers → API keys.
Contacts
A contact is anyone who has used your messenger or whom you've added: an anonymous visitor, a lead who has given contact details such as an email, or a user identified with your own user ID (external_id). See the contact object.
List contacts
/api/v1/contactsReturns a page of contacts. Combine the filters to narrow the list.
| Query parameter | Type | Description |
|---|---|---|
email | string | Only contacts with this email address. |
external_id | string | Only the contact with this user ID: one you set through the API, or the user_id the messenger got with a valid user_hash (see the contact object). |
type | string | visitor, lead or user. |
limit, cursor | See Pagination. |
curl "https://talkingdot.com/api/v1/contacts?email=ada@example.com" \
-H "Authorization: Bearer cn_live_xxxxxxxx"{
"data": [
{
"id": 1842,
"type": "user",
"external_id": "42",
"name": "Ada Lovelace",
"email": "ada@example.com",
"phone": "+44 20 7946 0958",
"company": "Analytical Engines Ltd",
"avatar_url": null,
"verified": true,
"location": {
"country": "GB",
"region": "England",
"city": "London",
"timezone": "Europe/London"
},
"language": "en",
"browser": "Chrome",
"os": "macOS",
"device": "desktop",
"custom_attributes": {
"plan": "pro",
"seats": 5
},
"tags": [
{ "id": 3, "name": "vip" }
],
"sessions": 12,
"page_views": 87,
"last_page_url": "https://www.example.com/pricing",
"unsubscribed": false,
"blocked": false,
"first_seen_at": "2026-09-14T08:02:11Z",
"last_seen_at": "2026-10-03T09:15:00Z",
"created_at": "2026-09-14T08:02:11Z",
"updated_at": "2026-10-03T09:15:00Z"
}
],
"meta": {
"next_cursor": null
}
}Create a contact
/api/v1/contactsAdds a contact, for example when someone signs up in your product. Returns 201 Created and the new contact, and sends the contact.created webhook. Send at least an email or an external_id. A contact with an external_id is a user; one with only contact details is a lead. An external_id another contact already has gets a 409 with the code conflict.
| Body field | Type | Description |
|---|---|---|
external_id | string | Your own ID for this user: the same value you pass as user_id to the messenger. Must be unique in the workspace. |
email | string | Email address. Must be valid. |
name | string | Full name. |
phone | string | Phone number. |
company | string | Company or organisation name. |
avatar_url | string | An https:// URL of the contact's picture. We copy it to our server in the background (up to 2 MB; at most 5 changes an hour per contact), so right after a change the API still returns the previous picture or null. |
unsubscribed | boolean | true when the contact doesn't want emails. |
custom_attributes | object | Key/value pairs with string, number or boolean values, for example {"plan": "pro"}. Nested objects and lists are refused with a 422. |
The text fields take a string, or null to clear them; any other type gets a 422. A contact made through the API has never visited your website, so it doesn't show as online: its first_seen_at and last_seen_at start a few minutes before created_at, and change when the person first uses the messenger.
curl https://talkingdot.com/api/v1/contacts \
-H "Authorization: Bearer cn_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"external_id": "43",
"email": "charles@example.com",
"name": "Charles Babbage",
"company": "Analytical Engines Ltd",
"custom_attributes": { "plan": "pro", "seats": 5 }
}'{
"data": {
"id": 1907,
"type": "user",
"external_id": "43",
"name": "Charles Babbage",
"email": "charles@example.com",
"phone": null,
"company": "Analytical Engines Ltd",
"avatar_url": null,
"verified": false,
"location": {
"country": null,
"region": null,
"city": null,
"timezone": null
},
"language": null,
"browser": null,
"os": null,
"device": null,
"custom_attributes": {
"plan": "pro",
"seats": 5
},
"tags": [],
"sessions": 0,
"page_views": 0,
"last_page_url": null,
"unsubscribed": false,
"blocked": false,
"first_seen_at": "2026-10-03T09:17:00Z",
"last_seen_at": "2026-10-03T09:17:00Z",
"created_at": "2026-10-03T09:20:00Z",
"updated_at": "2026-10-03T09:20:00Z"
}
}Retrieve a contact
/api/v1/contacts/{id}Returns one contact.
curl https://talkingdot.com/api/v1/contacts/1842 \
-H "Authorization: Bearer cn_live_xxxxxxxx"Update a contact
/api/v1/contacts/{id}Changes a contact. Takes the same fields as Create a contact; only the fields you send are changed. custom_attributes are merged into the existing ones: keys you send are added or overwritten, and a key set to null is removed. Returns the updated contact. An external_id another contact already has gets a 409 (conflict), as when you create one.
curl -X PATCH https://talkingdot.com/api/v1/contacts/1842 \
-H "Authorization: Bearer cn_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"company": "Difference Engines plc",
"custom_attributes": { "plan": "enterprise", "seats": 25 }
}'Delete a contact
/api/v1/contacts/{id}Permanently erases the contact and everything stored about them, including all of their conversations and messages, events, notes and page views. Use it for GDPR erasure requests. This can't be undone. A contact.deleted webhook is sent.
curl -X DELETE https://talkingdot.com/api/v1/contacts/1842 \
-H "Authorization: Bearer cn_live_xxxxxxxx"Contact events
/api/v1/contacts/{id}/eventsRecords something the contact did, such as paying an invoice or finishing onboarding. Events appear in the contact sidebar in the Inbox. This is the server-side version of TalkingDot('track', …) in the JavaScript API.
| Body field | Type | Description |
|---|---|---|
name | string | Required. The event name. Letters, numbers, spaces and . _ - : % & ! ? ( ) , + # ' /, up to 80 characters. A name with other characters, or a longer one, gets a 422. |
meta | object | Optional details: up to 20 flat values (strings, numbers or booleans). String values are cut to 255 characters. Nested objects and lists get a 422. |
curl https://talkingdot.com/api/v1/contacts/1842/events \
-H "Authorization: Bearer cn_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"name": "invoice_paid",
"meta": { "invoice": "INV-1042", "amount": 49, "currency": "EUR" }
}'Conversations
A conversation is a thread between a contact and your team. See the conversation object.
List conversations
/api/v1/conversationsReturns a page of conversations, without their messages.
| Query parameter | Type | Description |
|---|---|---|
status | string | open, snoozed or closed. |
assignee_id | integer | Only conversations assigned to this teammate. |
team_id | integer | Only conversations assigned to this team. |
contact_id | integer | Only this contact's conversations. |
limit, cursor | See Pagination. |
curl "https://talkingdot.com/api/v1/conversations?status=open&assignee_id=7" \
-H "Authorization: Bearer cn_live_xxxxxxxx"{
"data": [
{
"id": 5531,
"number": 318,
"contact_id": 1842,
"status": "open",
"priority": false,
"priority_level": "normal",
"ticket": null,
"assignee_id": 7,
"team_id": 2,
"channel": "chat",
"started_by": "contact",
"subject": null,
"source_url": "https://www.example.com/pricing",
"tags": [
{ "id": 5, "name": "billing" }
],
"rating": null,
"sentiment": null,
"first_response_seconds": 94,
"snoozed_until": null,
"waiting_since": "2026-10-03T09:15:00Z",
"last_message_at": "2026-10-03T09:15:00Z",
"created_at": "2026-10-03T09:01:30Z",
"closed_at": null,
"url": "https://talkingdot.com/app/12/inbox/5531"
}
],
"meta": {
"next_cursor": null
}
}Retrieve a conversation
/api/v1/conversations/{id}Returns one conversation with its messages. Check each message's type: message for replies, note for internal notes only your team sees, and event for timeline entries.
curl https://talkingdot.com/api/v1/conversations/5531 \
-H "Authorization: Bearer cn_live_xxxxxxxx"{
"data": {
"id": 5531,
"number": 318,
"contact_id": 1842,
"status": "open",
"priority": false,
"priority_level": "normal",
"ticket": null,
"assignee_id": 7,
"team_id": 2,
"channel": "chat",
"started_by": "contact",
"subject": null,
"source_url": "https://www.example.com/pricing",
"tags": [
{ "id": 5, "name": "billing" }
],
"rating": null,
"sentiment": null,
"first_response_seconds": 94,
"snoozed_until": null,
"waiting_since": "2026-10-03T09:15:00Z",
"last_message_at": "2026-10-03T09:15:00Z",
"created_at": "2026-10-03T09:01:30Z",
"closed_at": null,
"url": "https://talkingdot.com/app/12/inbox/5531",
"messages": [
{
"id": 88190,
"conversation_id": 5531,
"type": "message",
"author_type": "contact",
"author": { "id": 1842 },
"body": "Hi! Can I switch my plan to annual billing?",
"attachments": [],
"via": "widget",
"event": null,
"created_at": "2026-10-03T09:01:30Z"
},
{
"id": 88197,
"conversation_id": 5531,
"type": "message",
"author_type": "agent",
"author": { "id": 7, "name": "Grace Hopper", "email": "grace@example.com" },
"body": "Hi Ada, yes you can. Here's the invoice for the annual plan.",
"attachments": [
{
"name": "invoice-1042.pdf",
"url": "https://talkingdot.com/files/901/3f9c2a7b1e/invoice-1042.pdf",
"size": 48213,
"content_type": "application/pdf"
}
],
"via": "web",
"event": null,
"created_at": "2026-10-03T09:03:04Z"
},
{
"id": 88213,
"conversation_id": 5531,
"type": "message",
"author_type": "contact",
"author": { "id": 1842 },
"body": "Thanks! I've just paid it.",
"attachments": [],
"via": "widget",
"event": null,
"created_at": "2026-10-03T09:15:00Z"
}
]
}
}Start a conversation
/api/v1/conversationsStarts an outbound conversation: a new conversation with a contact, opened by a message from your team. Returns the new conversation.
| Body field | Type | Description |
|---|---|---|
contact_id | integer | Required. The contact to write to. |
body | string | Required. The first message. |
teammate_id | integer | Optional. The teammate the message is sent as. |
curl https://talkingdot.com/api/v1/conversations \
-H "Authorization: Bearer cn_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"contact_id": 1842,
"body": "Hi Ada, your annual plan is active. Anything else we can help with?",
"teammate_id": 7
}'Update a conversation
/api/v1/conversations/{id}Changes a conversation's status, assignment, priority, tags or ticket. Send only the fields you want to change. Returns the updated conversation. Every field is checked first: if one is wrong, you get a 422 and nothing is changed.
| Body field | Type | Description |
|---|---|---|
status | string | open, snoozed or closed. On a ticket, closed marks the ticket solved, open opens it again and snoozed puts it on hold; use ticket.status for the other ticket statuses. |
assignee_id | integer or null | The teammate to assign, or null to unassign. |
team_id | integer or null | The team to assign, or null to remove the team. |
priority | boolean | true sets the priority to high, false to normal. A JSON boolean, not the string "false". |
priority_level | string | low, normal, high or urgent. Send priority or priority_level, not both. |
ticket | object | Only for a conversation that is a ticket. Any of status (open, waiting, on_hold, solved or closed), until (with on_hold: when it comes back to open), type_id (see ticket types, or null), title, fields (an object of field keys and values; null clears a value) and due_at (an ISO 8601 time, or null for the automatic due time; plans with due times only). A ticket can only be solved or closed when its fields that are required to solve are filled in, counting the fields sent in the same request. Send status or ticket.status, not both. |
snoozed_until | string | When a snoozed conversation should reopen, as an ISO 8601 timestamp in the future. Use it with "status": "snoozed". |
tags | array of strings | The conversation's tags, by name, for example ["billing", "annual-plan"]. This replaces the current tags; tags that don't exist yet are created. |
# Assign to a teammate and team, mark as priority and tag it
curl -X PATCH https://talkingdot.com/api/v1/conversations/5531 \
-H "Authorization: Bearer cn_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"assignee_id": 7,
"team_id": 2,
"priority": true,
"tags": ["billing", "annual-plan"]
}'
# Snooze until Monday morning
curl -X PATCH https://talkingdot.com/api/v1/conversations/5531 \
-H "Authorization: Bearer cn_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "status": "snoozed", "snoozed_until": "2026-10-05T08:00:00Z" }'
# Close it
curl -X PATCH https://talkingdot.com/api/v1/conversations/5531 \
-H "Authorization: Bearer cn_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "status": "closed" }'
# A ticket: urgent, fill in a field and wait for the customer
curl -X PATCH https://talkingdot.com/api/v1/conversations/5531 \
-H "Authorization: Bearer cn_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"priority_level": "urgent",
"ticket": { "status": "waiting", "fields": { "order_number": "AC-1042" } }
}'Tickets
A ticket is a conversation with a status, a type, fields and due times. It keeps the conversation's id and number, so ticket #318 is conversation 5531 above, and every conversation in the API carries its ticket (or null). See the ticket object. Tickets must be turned on in Settings → Tickets; otherwise making one answers 403.
List tickets
/api/v1/ticketsReturns a page of conversations that are tickets, newest first, each with its ticket.
| Query parameter | Type | Description |
|---|---|---|
status | string | open, waiting, on_hold, solved, closed, or unsolved (open, waiting and on hold). |
type_id | integer | Only tickets of this type. |
priority | string | low, normal, high or urgent. |
assignee_id, team_id, contact_id | integer | As for conversations. |
overdue | string | true or false. Without due times on the plan, no ticket is overdue. |
limit, cursor | See Pagination. |
curl "https://talkingdot.com/api/v1/tickets?status=unsolved&priority=urgent" \
-H "Authorization: Bearer cn_live_xxxxxxxx"Retrieve a ticket
/api/v1/tickets/{id}The ticket's conversation, by its conversation id (404 when it is not a ticket). GET /api/v1/conversations/{id}/ticket returns only the ticket object.
Create a ticket
/api/v1/ticketsOpens a new ticket for a contact, as if they had sent it: a new conversation with the request as its first message. Returns the conversation with its ticket (201).
| Body field | Type | Description |
|---|---|---|
contact_id | integer | Required. The contact the ticket is for. |
title | string | Required. A short summary. |
body | string | Required. The request, in the customer's words. |
body_from | string | contact (the default) or note: the body becomes an internal note instead (needs a key that belongs to a teammate). |
type_id | integer | Optional. The ticket type. |
priority_level | string | Optional. low, normal, high or urgent (default: the type's). |
fields | object | Optional. Field keys and values, checked by field type. |
assignee_id, team_id | integer | Optional. Who gets it (default: the type's team and your assignment rules). |
curl https://talkingdot.com/api/v1/tickets \
-H "Authorization: Bearer cn_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"contact_id": 1842,
"title": "Order AC-1042 has not arrived",
"body": "I ordered two bags on Monday and the tracking has not moved since.",
"type_id": 2,
"priority_level": "high",
"fields": { "order_number": "AC-1042" }
}'The customer gets the “ticket opened” email only when their email address is proven (see email_proven on the contact).
Make a conversation a ticket, or turn it back
/api/v1/conversations/{id}/ticketMakes an existing conversation a ticket. Optional body fields: title (default: the subject or the customer's first message), type_id, priority_level and fields. Returns the conversation (201), or 409 when it is a ticket already.
/api/v1/conversations/{id}/ticketTurns a ticket back into a plain conversation: its status, type and fields are removed; the conversation and its messages stay. Returns the conversation.
To change a ticket (status, type, fields, due time), use PATCH /api/v1/conversations/{id} with ticket.
Ticket types and fields
/api/v1/ticket-typesEvery ticket type: id, name, emoji, color, description, priority_level (its default), team_id, reply_hours and solve_hours (its own due times, or null), form (a list of {"field", "required", "customer"}, by field key), in_messenger, archived and usable (false when it is archived or past the plan's number of types).
/api/v1/ticket-fieldsEvery custom ticket field: key (the name to use in fields), label, help, type (text, textarea, number, select, multiselect, checkbox, date, email or url), options (for select and multiselect), customer_visible, required_to_solve and archived.
Replies and notes
Add messages to an existing conversation, either from your team or on behalf of the contact. Each message is a message object.
Reply as a teammate
/api/v1/conversations/{id}/replySends a reply the contact sees, or adds an internal note only your team sees. Returns the new message.
| Body field | Type | Description |
|---|---|---|
body | string | Required. The text of the reply or note. |
type | string | Required. comment for a reply to the contact, or note for an internal note. Exactly one of these, in lowercase: anything else, or no type, gets a 422 and nothing is sent. |
teammate_id | integer | Optional. The teammate the reply or note is written as. |
curl https://talkingdot.com/api/v1/conversations/5531/reply \
-H "Authorization: Bearer cn_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"type": "comment",
"body": "Payment received, thank you! Your plan is now billed annually.",
"teammate_id": 7
}'{
"data": {
"id": 88220,
"conversation_id": 5531,
"type": "message",
"author_type": "agent",
"author": { "id": 7, "name": "Grace Hopper", "email": "grace@example.com" },
"body": "Payment received, thank you! Your plan is now billed annually.",
"attachments": [],
"via": "api",
"event": null,
"created_at": "2026-10-03T09:18:42Z"
}
}To leave a note for your team instead, send "type": "note". The contact never sees notes.
Reply as the contact
/api/v1/conversations/{id}/contact-replyAdds a message from the conversation's contact, as if they had written it themselves. Use it to bring in messages the contact sent through your own app or another channel.
| Body field | Type | Description |
|---|---|---|
body | string | Required. The contact's message. |
curl https://talkingdot.com/api/v1/conversations/5531/contact-reply \
-H "Authorization: Bearer cn_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "body": "Great, thanks for the quick help!" }'Messages feed
/api/v1/messagesThe newest messages across the whole workspace, newest first, each with its conversation. Use it for “new message” polling triggers in Zapier, Make or n8n (remember the highest id you have seen). Messages of locked conversations (ones that came in after a plan’s monthly limit) are left out, as everywhere else.
| Parameter | Type | Description |
|---|---|---|
type | string | message (default) or note (internal notes). |
author_type | string | contact, agent, bot or system. |
conversation_id | integer | Only this conversation's messages. |
limit, cursor | See pagination. |
curl "https://talkingdot.com/api/v1/messages?author_type=contact&limit=10" \
-H "Authorization: Bearer cn_live_xxxxxxxx"Payment requests
/api/v1/payment-requests/api/v1/payment-requests/{id}Payment requests sent in conversations (pay in chat), newest first. They are read only here: teammates send them from the inbox, and the AI with a teammate’s approval. amount and paid_amount are integers in the currency’s minor unit (₹1,500 is 150000 with "currency": "INR"); status is open, paid, expired or cancelled; pay_url is the provider’s page while the request is open.
| Parameter | Type | Description |
|---|---|---|
status | string | open, paid, expired or cancelled. |
conversation_id, contact_id | integer | Only this conversation’s or contact’s requests. |
limit, cursor | See pagination. |
curl "https://talkingdot.com/api/v1/payment-requests?status=paid&limit=10" \
-H "Authorization: Bearer cn_live_xxxxxxxx"{
"data": [{
"id": 52, "conversation_id": 1042, "contact_id": 311, "message_id": 88231,
"provider": "razorpay", "provider_reference": "plink_Pq8rT2xY", "status": "paid",
"amount": 150000, "currency": "INR", "amount_formatted": "₹1,500", "description": "Website setup",
"pay_url": null, "live_mode": true, "requested_by": { "id": 7, "name": "Priya" }, "requested_via": "agent",
"paid_amount": 150000, "payment_reference": "pay_Pq9aB3cD", "expires_at": "2026-11-12T09:15:00Z",
"paid_at": "2026-11-05T09:41:12Z", "created_at": "2026-11-05T09:15:00Z"
}],
"meta": { "next_cursor": null }
}Webhook subscriptions
Automation tools such as Zapier, Make and n8n subscribe to webhooks themselves (“REST hooks”): they create a subscription when a workflow is switched on and delete it when it is switched off. Deliveries are exactly those of Settings → Developers → Webhooks — signed, retried, sent only to public addresses — and the subscription shows there too, marked as added through the API.
A subscription belongs to the API key that created it: other keys can't see or delete it, and revoking the key removes it. Read-only keys can subscribe. A key can have up to 25 subscriptions.
Subscribe
/api/v1/webhooks| Body field | Type | Description |
|---|---|---|
target_url | string | Required. Where to send events: a public https:// (or http://) address. Local, private and cloud-metadata addresses are refused. |
events | array | Required. Event names (see events), or ["*"] for all. A single event string works too. |
curl https://talkingdot.com/api/v1/webhooks \
-H "Authorization: Bearer cn_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "target_url": "https://hooks.example.com/talkingdot", "events": ["conversation.created", "message.created"] }'The answer is 201 Created with the subscription. Its secret signs every delivery (the X-TalkingDot-Signature header) and is shown only in this answer, so store it now.
{
"data": {
"id": 31,
"target_url": "https://hooks.example.com/talkingdot",
"events": ["conversation.created", "message.created"],
"enabled": true,
"failures": 0,
"last_delivery": null,
"created_at": "2026-11-04T09:15:00Z",
"secret": "Kq3…48 characters…"
}
}List, retrieve, switch on and unsubscribe
/api/v1/webhooks/api/v1/webhooks/{id}/api/v1/webhooks/{id}/api/v1/webhooks/{id}The list holds this key's subscriptions only. DELETE answers {"data": {"id": 31, "deleted": true}}; a subscription made in Settings or by another key answers 404.
A subscription whose deliveries all fail for a day is switched off ("enabled": false; see failing endpoints). PATCH with {"enabled": true} switches it back on and starts the failure count again; {"enabled": false} switches it off.
curl -X PATCH https://talkingdot.com/api/v1/webhooks/31 \
-H "Authorization: Bearer cn_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "enabled": true }'
curl -X DELETE https://talkingdot.com/api/v1/webhooks/31 \
-H "Authorization: Bearer cn_live_xxxxxxxx"Events and sample data
/api/v1/webhooks/events/api/v1/webhooks/samples?event=message.createdevents lists every event with a description (for a drop-down). samples returns up to three payloads shaped exactly like real deliveries, built from your latest conversations, messages or contacts (never locked ones) — or one example when there is nothing yet. Each has "sample": true and a stable id, so it works as test data (“perform list”) in Zapier or Make.
Teammates and teams
List teammates
/api/v1/teammatesReturns the people in your workspace. Use a teammate's id as assignee_id or teammate_id. role is owner, admin or agent; availability is online or away. Teammates, teams, tags and collections are short lists that come complete in one answer, without meta or pagination.
curl https://talkingdot.com/api/v1/teammates \
-H "Authorization: Bearer cn_live_xxxxxxxx"{
"data": [
{
"id": 7,
"name": "Grace Hopper",
"email": "grace@example.com",
"role": "admin",
"availability": "online",
"avatar_url": null
}
]
}List teams
/api/v1/teamsReturns your workspace's teams. Use a team's id as team_id when you update a conversation.
curl https://talkingdot.com/api/v1/teams \
-H "Authorization: Bearer cn_live_xxxxxxxx"Tags
/api/v1/tagsReturns your workspace's tags, each with an id and a name. Tag conversations by name with PATCH /api/v1/conversations/{id}.
curl https://talkingdot.com/api/v1/tags \
-H "Authorization: Bearer cn_live_xxxxxxxx"Help center
Manage the articles in your help center. Articles are grouped into collections and are either draft or published.
List collections
/api/v1/collectionsReturns your help-center collections. Use a collection's id as an article's collection_id.
curl https://talkingdot.com/api/v1/collections \
-H "Authorization: Bearer cn_live_xxxxxxxx"List articles
/api/v1/articlesReturns a page of articles.
| Query parameter | Type | Description |
|---|---|---|
status | string | draft or published. |
limit, cursor | See Pagination. |
curl "https://talkingdot.com/api/v1/articles?status=published" \
-H "Authorization: Bearer cn_live_xxxxxxxx"Retrieve an article
/api/v1/articles/{id}Returns one article, including its HTML body and its view and "was this helpful?" counts.
curl https://talkingdot.com/api/v1/articles/64 \
-H "Authorization: Bearer cn_live_xxxxxxxx"{
"data": {
"id": 64,
"title": "How refunds work",
"slug": "how-refunds-work",
"excerpt": "Where to request a refund and what happens next.",
"body_html": "<p>Open <strong>Billing</strong> and choose <strong>Request refund</strong>.</p>",
"status": "published",
"collection_id": 3,
"views": 1204,
"helpful": 87,
"unhelpful": 6,
"url": "https://talkingdot.com/help/acme/articles/64-how-refunds-work",
"created_at": "2026-08-21T14:00:00Z",
"updated_at": "2026-09-30T10:12:45Z"
}
}Create an article
/api/v1/articlesAdds an article. Returns the new article.
| Body field | Type | Description |
|---|---|---|
title | string | Required. The article title. |
body_html | string | The article body as HTML. |
collection_id | integer | The collection to put it in. |
status | string | draft or published. |
curl https://talkingdot.com/api/v1/articles \
-H "Authorization: Bearer cn_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"title": "Switching to annual billing",
"body_html": "<p>Open <strong>Billing</strong>, choose <strong>Change plan</strong> and pick <strong>Annual</strong>.</p>",
"collection_id": 3,
"status": "draft"
}'Update an article
/api/v1/articles/{id}Changes an article. Takes the same fields as Create an article; send only the ones you want to change. Returns the updated article.
curl -X PATCH https://talkingdot.com/api/v1/articles/64 \
-H "Authorization: Bearer cn_live_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "status": "published" }'Delete an article
/api/v1/articles/{id}Deletes an article. It disappears from your help center and from search in the messenger.
curl -X DELETE https://talkingdot.com/api/v1/articles/64 \
-H "Authorization: Bearer cn_live_xxxxxxxx"Object reference
The same objects are used in API responses and in webhook payloads. Timestamps are ISO 8601 in UTC; fields without a value are null.
Contact
| Field | Type | Description |
|---|---|---|
id | integer | Unique ID of the contact. |
type | string | visitor (anonymous), lead (has given contact details, such as an email) or user (has an external_id). |
external_id | string or null | Your own user ID: set through the API, or the user_id passed to the messenger with a valid user_hash. A user_id without a valid user_hash is never stored here (anyone could type one in their browser): it is kept as the unverified_user_id custom attribute instead, and the contact stays a visitor or lead. See Identity verification. |
name | string or null | Full name. |
email | string or null | Email address, in lowercase. |
phone | string or null | Phone number. |
company | string or null | Company or organisation. |
avatar_url | string or null | URL of the contact's picture (our own copy). |
email_proven | boolean | true when the email came from a trusted source (signed in by your site, an authenticated email, a code the customer entered, a teammate, an import or the API), false when someone only typed it into the messenger. Match customers on proven emails only. |
verified | boolean | true when the identity was proven with a valid user_hash. See Identity verification. |
location | object | country (two-letter code, such as GB), region, city and timezone (such as Europe/London). Each can be null. |
language | string or null | Browser language code, such as en. |
browser | string or null | Browser name, such as Chrome. |
os | string or null | Operating system, such as macOS. |
device | string or null | desktop, tablet or mobile. |
custom_attributes | object | Your own key/value data. An empty object when there is none. |
tags | array | Tags on the contact, each {"id", "name"}. |
sessions | integer | Number of visits. |
page_views | integer | Number of pages viewed. |
last_page_url | string or null | The last page the contact viewed. |
unsubscribed | boolean | true when the contact has unsubscribed from emails. |
blocked | boolean | true when your team has blocked the contact. |
first_seen_at | timestamp | When the contact was first seen. |
last_seen_at | timestamp | When the contact was last seen. |
created_at | timestamp | When the contact was created. |
updated_at | timestamp or null | When the contact's details last changed. |
Conversation
| Field | Type | Description |
|---|---|---|
id | integer | Unique ID of the conversation. |
number | integer | The conversation's number within your workspace. |
contact_id | integer | The contact the conversation is with. |
status | string | open, snoozed or closed. |
priority | boolean | true when the priority is high or urgent (the old priority flag). |
priority_level | string | low, normal, high or urgent. |
ticket | object or null | The ticket, when the conversation is one; null otherwise. |
assignee_id | integer or null | The assigned teammate. |
team_id | integer or null | The assigned team. |
channel | string | Where the conversation happens: chat (the messenger on your website, also for conversations started through the API), email, whatsapp, telegram, messenger (Facebook Messenger), instagram or import (history imported from another tool). |
started_by | string | Who started the conversation: contact, agent, auto (an auto message), api or import. |
subject | string or null | Subject line, mainly for email conversations. |
source_url | string or null | The page the conversation started on. |
tags | array | Tags on the conversation, each {"id", "name"}. |
rating | object or null | The contact's rating: score (1 to 5), comment and rated_at. null until they rate. |
sentiment | string or null | How the contact felt — positive, neutral or negative — noted by the AI assistant shortly after the conversation is closed, when Auto-tags & visitor mood is on. null otherwise. |
first_response_seconds | integer or null | Seconds from the start of the conversation to your team's first reply. |
snoozed_until | timestamp or null | When a snoozed conversation reopens. |
waiting_since | timestamp or null | When the contact started waiting for a reply; null when your team has replied. |
last_message_at | timestamp or null | Time of the latest message. |
created_at | timestamp | When the conversation started. |
closed_at | timestamp or null | When it was closed. |
locked | boolean | true when it came in after the Free plan's monthly limit: its messages, subject and rating comment are hidden until the workspace is upgraded. |
url | string | Link to the conversation in the Inbox (for teammates). |
Ticket
The ticket of a conversation. Its title is the conversation's subject, and its number the conversation's number.
| Field | Type | Description |
|---|---|---|
number | integer | The ticket number, the same as the conversation's. |
status | string | open, waiting (on the customer), on_hold, solved or closed. |
type | object or null | The ticket type: id and name. |
source | string | How it was made: agent (a teammate), form (the customer, in the messenger), api, rule (an automation rule), mcp (an AI app) or email. |
fields | object | The custom field values, by field key. An empty object when there are none. |
due_at | timestamp or null | When it should be solved (plans with due times). |
reply_due_at | timestamp or null | When the first reply is due, until your team has replied. |
overdue | boolean | true when it is open and past due_at, or past reply_due_at without a reply. |
first_reply_seconds | integer or null | Seconds from the ticket's start to your team's first reply. |
solved_at | timestamp or null | When it was last solved. |
closed_at | timestamp or null | When it was closed. |
reopens | integer | How many times it opened again after being solved or closed. |
created_at | timestamp | When it became a ticket. |
Message
| Field | Type | Description |
|---|---|---|
id | integer | Unique ID of the message. |
conversation_id | integer | The conversation it belongs to. |
type | string | message (seen by the contact), note (internal) or event (a timeline entry, such as an assignment). |
author_type | string | contact, agent (a teammate), bot or system. |
author | object or null | For a teammate: id, name and email. For the contact: id. null for bot and system messages. |
body | string | The message text. Empty for timeline entries (event). |
attachments | array | Files, each with name, url, size (bytes) and content_type. |
via | string | Where it was written: widget (the messenger), web (the Inbox), email, api, bot or auto. For timeline entries it doesn't say where the change was made (it shows web even for a change made through the API). |
event | object or null | For timeline entries only (null otherwise): action says what happened, such as assigned, unassigned, team_assigned, closed, reopened, snoozed, prioritized, deprioritized, rated, or for tickets ticket_created, ticket_status, ticket_type, ticket_due, ticket_fields and ticket_removed; by is the ID of the teammate who did it, or null. Some actions add details: assignee_id, team_id, until (snoozed or on hold until), rating, number (the conversation merged into this one, or the ticket number), level (the new priority level), from and to (the old and new status or type), reason (why a ticket's status changed by itself, such as customer_reply or waiting_timeout), type_id, source and due_at. |
created_at | timestamp | When it was sent. |