Conversations

List conversations

GET /v1/c/{slug}/conversations · Scopes: conversations:read

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).

Query parameters

Field	Type	Required	Notes
`view`	one of `mine`, `team`, `queue`, `waiting_contact`, `snoozed`, `closed`, `mentions`, `all`	no	default `"mine"`
`limit`	integer	no	up to 100; at least 1; default `50`
`before`	string (date-time)	no
`q`	string	no	up to 200 characters
`tag`	string (uuid)	no

Request example

curl -X GET "https://api.donetalk.com/v1/c/demo/conversations" \
  -H "Authorization: Bearer $DONETALK_KEY"

Response 200

{
  "conversations": [
    {
      "id": "01a3c0de-7a11-7b22-8c33-9d44e55f6677",
      "status": "active",
      "handler": "human",
      "priority": "normal",
      "teamId": "01a0cb22-89c0-7e02-b96b-3f4731dde701",
      "assigneeId": "01a0cac1-4a6f-7646-b5f8-c1d19090016a",
      "unreadCount": 1,
      "lastMessageAt": "2026-10-23T13:05:52.000Z",
      "lastInboundAt": "2026-10-23T13:05:52.000Z",
      "sessionWindowEndsAt": "2026-10-24T13:05:52.000Z",
      "snoozedUntil": null,
      "sourceKind": "campaign",
      "createdAt": "2026-10-23T13:02:11.000Z",
      "tags": [
        {
          "id": "01a12150-3610-7c00-b680-188c2b4c7313",
          "name": {
            "pt-BR": "VIP",
            "en": "VIP",
            "es": "VIP"
          },
          "color": "#92400e"
        }
      ],
      "contact": {
        "id": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
        "name": "Ana Souza",
        "address": "5548999990001"
      },
      "channel": {
        "id": "01a0cccc-0000-7000-8000-000000000002",
        "name": "Captei"
      },
      "lastMessage": {
        "body": "Quero o cupom",
        "direction": "inbound",
        "type": "button",
        "status": "received"
      }
    }
  ]
}

Possible errors

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Open a conversation with a template

POST /v1/c/{slug}/conversations · Scopes: messages:send_template

For an existing contact. assigneeMemberId picks who handles it; without one, it waits for the reply and joins the team's queue.

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).

Request body

Field	Type	Required	Notes
`contactId`	string (uuid)	yes
`channelId`	string (uuid)	no
`templateId`	string (uuid)	yes
`parameters`	object	no	default `{}`
`headerUploadId`	string (uuid)	no
`headerLink`	string (uri)	no	up to 2000 characters
`teamId`	string (uuid)	no	null
`goal`	string	no	up to 60 characters
`assigneeMemberId`	string (uuid)	no

Request example

curl -X POST "https://api.donetalk.com/v1/c/demo/conversations" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "contactId": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
  "templateId": "01a0cad0-0000-7000-8000-000000000002",
  "parameters": {
    "1": "Ana"
  }
}'

Response 201

{
  "conversation": {
    "id": "01a3c0de-7a11-7b22-8c33-9d44e55f6677"
  },
  "message": {
    "id": "01a3c0de-8b22-7c33-9d44-0e55f6677889"
  }
}

Possible errors

401 unauthorized
403 insufficient_scope
404 contact_not_found
409 template_not_approved
422 validation_failed
429 rate_limited

Get a conversation

GET /v1/c/{slug}/conversations/{id} · Scopes: conversations:read

The conversation with its messages, events (assignments, transfers) and, once closed, the outcome.

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).
`id`	The record's id.

Request example

curl -X GET "https://api.donetalk.com/v1/c/demo/conversations/:id" \
  -H "Authorization: Bearer $DONETALK_KEY"

Response 200

{
  "conversation": {
    "id": "01a3c0de-7a11-7b22-8c33-9d44e55f6677",
    "status": "active",
    "handler": "human",
    "priority": "normal",
    "teamId": "01a0cb22-89c0-7e02-b96b-3f4731dde701",
    "assigneeId": "01a0cac1-4a6f-7646-b5f8-c1d19090016a",
    "unreadCount": 1,
    "lastMessageAt": "2026-10-23T13:05:52.000Z",
    "lastInboundAt": "2026-10-23T13:05:52.000Z",
    "sessionWindowEndsAt": "2026-10-24T13:05:52.000Z",
    "snoozedUntil": null,
    "sourceKind": "campaign",
    "createdAt": "2026-10-23T13:02:11.000Z",
    "tags": [
      {
        "id": "01a12150-3610-7c00-b680-188c2b4c7313",
        "name": {
          "pt-BR": "VIP",
          "en": "VIP",
          "es": "VIP"
        },
        "color": "#92400e"
      }
    ],
    "contact": {
      "id": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
      "name": "Ana Souza",
      "address": "5548999990001"
    },
    "channel": {
      "id": "01a0cccc-0000-7000-8000-000000000002",
      "name": "Captei"
    },
    "lastMessage": {
      "body": "Quero o cupom",
      "direction": "inbound",
      "type": "button",
      "status": "received"
    },
    "goal": null,
    "outcome": null,
    "closedAt": null
  },
  "messages": [
    {
      "id": "01a3c0de-8b22-7c33-9d44-0e55f6677889",
      "conversationId": "01a3c0de-7a11-7b22-8c33-9d44e55f6677",
      "direction": "outbound",
      "author": {
        "kind": "campaign",
        "id": "01a2b3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b"
      },
      "type": "template",
      "body": "Oi Ana! Seu cupom ANA10 vale até sexta. Quer usar agora?",
      "status": "read",
      "error": null,
      "campaignId": "01a2b3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b",
      "createdAt": "2026-10-23T13:02:11.000Z"
    }
  ],
  "pinned": [],
  "events": []
}

Possible errors

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Send a message in the conversation

POST /v1/c/{slug}/conversations/{id}/messages · Scopes: messages:send_template · messages:send_text

type: template with the messages:send_template scope. text and media (a file from POST /uploads) need messages:send_text and the 24-hour window open.

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).
`id`	The record's id.

Request body

Field	Type	Required	Notes
`type`	one of `text`	yes
`text`	string	yes	up to 4096 characters
`replyToProviderMessageId`	string	no
`linkPreview`	boolean	no
`gateDecisionId`	string (uuid)	no
`gateAction`	one of `accepted`, `edited`, `overridden`	no
`templateId`	string (uuid)	yes
`parameters`	object	no	default `{}`
`headerUploadId`	string (uuid)	no
`headerLink`	string (uri)	no	up to 2000 characters
`uploadId`	string (uuid)	yes
`caption`	string	no	up to 1024 characters
`contactIds`	list of string (uuid)	yes	up to 10

Request example

curl -X POST "https://api.donetalk.com/v1/c/demo/conversations/:id/messages" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "text",
  "text": "Oi Ana! Seu pedido saiu para entrega."
}'

Response 202

{
  "message": {
    "id": "01a3c0de-8b22-7c33-9d44-0e55f6677889",
    "status": "queued",
    "createdAt": "2026-10-23T13:02:11.000Z",
    "media": null
  }
}

Possible errors

401 unauthorized
403 insufficient_scope
403 integration_template_only
409 window_closed
422 validation_failed
429 rate_limited

Close with an outcome

POST /v1/c/{slug}/conversations/{id}/close · Scopes: conversations:write

outcomeCode comes from GET /outcomes. With ifNoReplyHours, it closes only if the contact does not answer in that time.

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).
`id`	The record's id.

Request body

Field	Type	Required	Notes
`outcomeCode`	string	yes	up to 60 characters
`note`	string	no	up to 4000 characters
`ifNoReplyHours`	integer	no	up to 720; at least 1

Request example

curl -X POST "https://api.donetalk.com/v1/c/demo/conversations/:id/close" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "outcomeCode": "converted",
  "note": "Fechou o plano anual."
}'

Response 200

{
  "ok": true,
  "isSuccess": true
}

Possible errors

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Reopen

POST /v1/c/{slug}/conversations/{id}/reopen · Scopes: conversations:write

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).
`id`	The record's id.

Request example

curl -X POST "https://api.donetalk.com/v1/c/demo/conversations/:id/reopen" \
  -H "Authorization: Bearer $DONETALK_KEY"

Response 200

{
  "ok": true
}

Possible errors

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Upload a file

POST /v1/c/{slug}/uploads · Scopes: messages:send_text · campaigns:write · messages:send_template

multipart/form-data with the file field (and intent: media, document, audio, sticker). Returns the id to send in a message or set as a campaign's header.

Path parameters

Field	Notes
`slug`	The company's identifier in DoneTalk (the key's own).

Request body

multipart/form-data: file + intent (media, document, audio, sticker).

Request example

curl -X POST "https://api.donetalk.com/v1/c/demo/uploads" \
  -H "Authorization: Bearer $DONETALK_KEY"

Response 201

{
  "upload": {
    "id": "01a3d1e2-f3a4-7b5c-8d6e-7f8091a2b3c4",
    "mime": "image/jpeg",
    "sizeBytes": 182340,
    "filename": "cupom.jpg",
    "kind": "image",
    "voice": false,
    "conversion": null,
    "durationMs": null,
    "width": 1080,
    "height": 1080
  }
}

Possible errors

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

This page as Markdown