1. Docs
  2. 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 URLhttps://talkingdot.com/api/v1
AuthenticationAuthorization: Bearer <api key>
FormatJSON request bodies and JSON responses
IDsIntegers
TimestampsISO 8601 in UTC, for example 2026-10-03T09:15:00Z
Rate limit120 requests per minute per API key

Try it with your key:

Shell
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.

Shell
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:

JSON
{
  "data": {
    "id": 1842,
    "name": "Ada Lovelace",
    "email": "ada@example.com"
  }
}

For lists, data is an array and meta holds the pagination cursor:

JSON
{
  "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:

ParameterTypeDescription
limitintegerHow many results to return, from 1 to 100. Default 25.
cursorstringThe 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.

Shell
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+:

JavaScript
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.

JSON
{
  "error": {
    "code": "not_found",
    "message": "Contact not found."
  }
}
HTTP statuscodeMeaning
400invalid_jsonThe request body isn't a JSON object (broken JSON, or a list instead of an object).
401unauthorizedThe API key is missing, invalid or revoked — also when the teammate who created it is no longer on the team.
402payment_requiredThe conversation came in after the Free plan's monthly limit: replies to it are refused until the workspace is upgraded.
403forbiddenThe 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.
404not_foundThe object doesn't exist in this workspace, or the endpoint doesn't exist.
405method_not_allowedThe endpoint exists but doesn't take this HTTP method. The Allow header lists the ones it takes.
409conflictAnother contact already has this external_id (when you create or update a contact).
422validationThe 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.
429rate_limitedToo 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:

HeaderDescription
X-RateLimit-LimitRequests allowed per minute for this key (120).
X-RateLimit-RemainingRequests left in the current minute.
Retry-AfterSent with a 429 response: seconds to wait before retrying (until the current minute's count starts again).
HTTP
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

GET/api/v1/me

Returns details of the workspace your API key belongs to. Use it to check that a key works before you use it for anything else.

Shell
curl https://talkingdot.com/api/v1/me \
  -H "Authorization: Bearer cn_live_xxxxxxxx"
JSON
{
  "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

GET/api/v1/contacts

Returns a page of contacts. Combine the filters to narrow the list.

Query parameterTypeDescription
emailstringOnly contacts with this email address.
external_idstringOnly 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).
typestringvisitor, lead or user.
limit, cursorSee Pagination.
Shell
curl "https://talkingdot.com/api/v1/contacts?email=ada@example.com" \
  -H "Authorization: Bearer cn_live_xxxxxxxx"
JSON
{
  "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

POST/api/v1/contacts

Adds 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 fieldTypeDescription
external_idstringYour own ID for this user: the same value you pass as user_id to the messenger. Must be unique in the workspace.
emailstringEmail address. Must be valid.
namestringFull name.
phonestringPhone number.
companystringCompany or organisation name.
avatar_urlstringAn 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.
unsubscribedbooleantrue when the contact doesn't want emails.
custom_attributesobjectKey/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.

Shell
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 }
  }'
JSON
{
  "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

GET/api/v1/contacts/{id}

Returns one contact.

Shell
curl https://talkingdot.com/api/v1/contacts/1842 \
  -H "Authorization: Bearer cn_live_xxxxxxxx"

Update a contact

PATCH/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.

Shell
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

DELETE/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.

Shell
curl -X DELETE https://talkingdot.com/api/v1/contacts/1842 \
  -H "Authorization: Bearer cn_live_xxxxxxxx"

Contact events

POST/api/v1/contacts/{id}/events

Records 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 fieldTypeDescription
namestringRequired. The event name. Letters, numbers, spaces and . _ - : % & ! ? ( ) , + # ' /, up to 80 characters. A name with other characters, or a longer one, gets a 422.
metaobjectOptional details: up to 20 flat values (strings, numbers or booleans). String values are cut to 255 characters. Nested objects and lists get a 422.
Shell
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

GET/api/v1/conversations

Returns a page of conversations, without their messages.

Query parameterTypeDescription
statusstringopen, snoozed or closed.
assignee_idintegerOnly conversations assigned to this teammate.
team_idintegerOnly conversations assigned to this team.
contact_idintegerOnly this contact's conversations.
limit, cursorSee Pagination.
Shell
curl "https://talkingdot.com/api/v1/conversations?status=open&assignee_id=7" \
  -H "Authorization: Bearer cn_live_xxxxxxxx"
JSON
{
  "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

GET/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.

Shell
curl https://talkingdot.com/api/v1/conversations/5531 \
  -H "Authorization: Bearer cn_live_xxxxxxxx"
JSON
{
  "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

POST/api/v1/conversations

Starts an outbound conversation: a new conversation with a contact, opened by a message from your team. Returns the new conversation.

Body fieldTypeDescription
contact_idintegerRequired. The contact to write to.
bodystringRequired. The first message.
teammate_idintegerOptional. The teammate the message is sent as.
Shell
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

PATCH/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 fieldTypeDescription
statusstringopen, 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_idinteger or nullThe teammate to assign, or null to unassign.
team_idinteger or nullThe team to assign, or null to remove the team.
prioritybooleantrue sets the priority to high, false to normal. A JSON boolean, not the string "false".
priority_levelstringlow, normal, high or urgent. Send priority or priority_level, not both.
ticketobjectOnly 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_untilstringWhen a snoozed conversation should reopen, as an ISO 8601 timestamp in the future. Use it with "status": "snoozed".
tagsarray of stringsThe conversation's tags, by name, for example ["billing", "annual-plan"]. This replaces the current tags; tags that don't exist yet are created.
Shell
# 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

GET/api/v1/tickets

Returns a page of conversations that are tickets, newest first, each with its ticket.

Query parameterTypeDescription
statusstringopen, waiting, on_hold, solved, closed, or unsolved (open, waiting and on hold).
type_idintegerOnly tickets of this type.
prioritystringlow, normal, high or urgent.
assignee_id, team_id, contact_idintegerAs for conversations.
overduestringtrue or false. Without due times on the plan, no ticket is overdue.
limit, cursorSee Pagination.
Shell
curl "https://talkingdot.com/api/v1/tickets?status=unsolved&priority=urgent" \
  -H "Authorization: Bearer cn_live_xxxxxxxx"

Retrieve a ticket

GET/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

POST/api/v1/tickets

Opens 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 fieldTypeDescription
contact_idintegerRequired. The contact the ticket is for.
titlestringRequired. A short summary.
bodystringRequired. The request, in the customer's words.
body_fromstringcontact (the default) or note: the body becomes an internal note instead (needs a key that belongs to a teammate).
type_idintegerOptional. The ticket type.
priority_levelstringOptional. low, normal, high or urgent (default: the type's).
fieldsobjectOptional. Field keys and values, checked by field type.
assignee_id, team_idintegerOptional. Who gets it (default: the type's team and your assignment rules).
Shell
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

POST/api/v1/conversations/{id}/ticket

Makes 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.

DELETE/api/v1/conversations/{id}/ticket

Turns 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

GET/api/v1/ticket-types

Every 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).

GET/api/v1/ticket-fields

Every 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

POST/api/v1/conversations/{id}/reply

Sends a reply the contact sees, or adds an internal note only your team sees. Returns the new message.

Body fieldTypeDescription
bodystringRequired. The text of the reply or note.
typestringRequired. 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_idintegerOptional. The teammate the reply or note is written as.
Shell
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
  }'
JSON
{
  "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

POST/api/v1/conversations/{id}/contact-reply

Adds 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 fieldTypeDescription
bodystringRequired. The contact's message.
Shell
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

GET/api/v1/messages

The 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.

ParameterTypeDescription
typestringmessage (default) or note (internal notes).
author_typestringcontact, agent, bot or system.
conversation_idintegerOnly this conversation's messages.
limit, cursorSee pagination.
Shell
curl "https://talkingdot.com/api/v1/messages?author_type=contact&limit=10" \
  -H "Authorization: Bearer cn_live_xxxxxxxx"

Payment requests

GET/api/v1/payment-requests
GET/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.

ParameterTypeDescription
statusstringopen, paid, expired or cancelled.
conversation_id, contact_idintegerOnly this conversation’s or contact’s requests.
limit, cursorSee pagination.
Shell
curl "https://talkingdot.com/api/v1/payment-requests?status=paid&limit=10" \
  -H "Authorization: Bearer cn_live_xxxxxxxx"
JSON
{
  "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

POST/api/v1/webhooks
Body fieldTypeDescription
target_urlstringRequired. Where to send events: a public https:// (or http://) address. Local, private and cloud-metadata addresses are refused.
eventsarrayRequired. Event names (see events), or ["*"] for all. A single event string works too.
Shell
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.

JSON
{
  "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

GET/api/v1/webhooks
GET/api/v1/webhooks/{id}
PATCH/api/v1/webhooks/{id}
DELETE/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.

Shell
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

GET/api/v1/webhooks/events
GET/api/v1/webhooks/samples?event=message.created

events 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

GET/api/v1/teammates

Returns 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.

Shell
curl https://talkingdot.com/api/v1/teammates \
  -H "Authorization: Bearer cn_live_xxxxxxxx"
JSON
{
  "data": [
    {
      "id": 7,
      "name": "Grace Hopper",
      "email": "grace@example.com",
      "role": "admin",
      "availability": "online",
      "avatar_url": null
    }
  ]
}

List teams

GET/api/v1/teams

Returns your workspace's teams. Use a team's id as team_id when you update a conversation.

Shell
curl https://talkingdot.com/api/v1/teams \
  -H "Authorization: Bearer cn_live_xxxxxxxx"

Tags

GET/api/v1/tags

Returns your workspace's tags, each with an id and a name. Tag conversations by name with PATCH /api/v1/conversations/{id}.

Shell
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

GET/api/v1/collections

Returns your help-center collections. Use a collection's id as an article's collection_id.

Shell
curl https://talkingdot.com/api/v1/collections \
  -H "Authorization: Bearer cn_live_xxxxxxxx"

List articles

GET/api/v1/articles

Returns a page of articles.

Query parameterTypeDescription
statusstringdraft or published.
limit, cursorSee Pagination.
Shell
curl "https://talkingdot.com/api/v1/articles?status=published" \
  -H "Authorization: Bearer cn_live_xxxxxxxx"

Retrieve an article

GET/api/v1/articles/{id}

Returns one article, including its HTML body and its view and "was this helpful?" counts.

Shell
curl https://talkingdot.com/api/v1/articles/64 \
  -H "Authorization: Bearer cn_live_xxxxxxxx"
JSON
{
  "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

POST/api/v1/articles

Adds an article. Returns the new article.

Body fieldTypeDescription
titlestringRequired. The article title.
body_htmlstringThe article body as HTML.
collection_idintegerThe collection to put it in.
statusstringdraft or published.
Shell
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

PATCH/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.

Shell
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

DELETE/api/v1/articles/{id}

Deletes an article. It disappears from your help center and from search in the messenger.

Shell
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

FieldTypeDescription
idintegerUnique ID of the contact.
typestringvisitor (anonymous), lead (has given contact details, such as an email) or user (has an external_id).
external_idstring or nullYour 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.
namestring or nullFull name.
emailstring or nullEmail address, in lowercase.
phonestring or nullPhone number.
companystring or nullCompany or organisation.
avatar_urlstring or nullURL of the contact's picture (our own copy).
email_provenbooleantrue 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.
verifiedbooleantrue when the identity was proven with a valid user_hash. See Identity verification.
locationobjectcountry (two-letter code, such as GB), region, city and timezone (such as Europe/London). Each can be null.
languagestring or nullBrowser language code, such as en.
browserstring or nullBrowser name, such as Chrome.
osstring or nullOperating system, such as macOS.
devicestring or nulldesktop, tablet or mobile.
custom_attributesobjectYour own key/value data. An empty object when there is none.
tagsarrayTags on the contact, each {"id", "name"}.
sessionsintegerNumber of visits.
page_viewsintegerNumber of pages viewed.
last_page_urlstring or nullThe last page the contact viewed.
unsubscribedbooleantrue when the contact has unsubscribed from emails.
blockedbooleantrue when your team has blocked the contact.
first_seen_attimestampWhen the contact was first seen.
last_seen_attimestampWhen the contact was last seen.
created_attimestampWhen the contact was created.
updated_attimestamp or nullWhen the contact's details last changed.

Conversation

FieldTypeDescription
idintegerUnique ID of the conversation.
numberintegerThe conversation's number within your workspace.
contact_idintegerThe contact the conversation is with.
statusstringopen, snoozed or closed.
prioritybooleantrue when the priority is high or urgent (the old priority flag).
priority_levelstringlow, normal, high or urgent.
ticketobject or nullThe ticket, when the conversation is one; null otherwise.
assignee_idinteger or nullThe assigned teammate.
team_idinteger or nullThe assigned team.
channelstringWhere 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_bystringWho started the conversation: contact, agent, auto (an auto message), api or import.
subjectstring or nullSubject line, mainly for email conversations.
source_urlstring or nullThe page the conversation started on.
tagsarrayTags on the conversation, each {"id", "name"}.
ratingobject or nullThe contact's rating: score (1 to 5), comment and rated_at. null until they rate.
sentimentstring or nullHow 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_secondsinteger or nullSeconds from the start of the conversation to your team's first reply.
snoozed_untiltimestamp or nullWhen a snoozed conversation reopens.
waiting_sincetimestamp or nullWhen the contact started waiting for a reply; null when your team has replied.
last_message_attimestamp or nullTime of the latest message.
created_attimestampWhen the conversation started.
closed_attimestamp or nullWhen it was closed.
lockedbooleantrue when it came in after the Free plan's monthly limit: its messages, subject and rating comment are hidden until the workspace is upgraded.
urlstringLink 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.

FieldTypeDescription
numberintegerThe ticket number, the same as the conversation's.
statusstringopen, waiting (on the customer), on_hold, solved or closed.
typeobject or nullThe ticket type: id and name.
sourcestringHow it was made: agent (a teammate), form (the customer, in the messenger), api, rule (an automation rule), mcp (an AI app) or email.
fieldsobjectThe custom field values, by field key. An empty object when there are none.
due_attimestamp or nullWhen it should be solved (plans with due times).
reply_due_attimestamp or nullWhen the first reply is due, until your team has replied.
overduebooleantrue when it is open and past due_at, or past reply_due_at without a reply.
first_reply_secondsinteger or nullSeconds from the ticket's start to your team's first reply.
solved_attimestamp or nullWhen it was last solved.
closed_attimestamp or nullWhen it was closed.
reopensintegerHow many times it opened again after being solved or closed.
created_attimestampWhen it became a ticket.

Message

FieldTypeDescription
idintegerUnique ID of the message.
conversation_idintegerThe conversation it belongs to.
typestringmessage (seen by the contact), note (internal) or event (a timeline entry, such as an assignment).
author_typestringcontact, agent (a teammate), bot or system.
authorobject or nullFor a teammate: id, name and email. For the contact: id. null for bot and system messages.
bodystringThe message text. Empty for timeline entries (event).
attachmentsarrayFiles, each with name, url, size (bytes) and content_type.
viastringWhere 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).
eventobject or nullFor 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_attimestampWhen it was sent.
Last updated November 20, 2026 Something unclear? Tell us