Atendimentos

Listar atendimentos

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

Parâmetros do endereço

Campo	Detalhes
`slug`	O identificador da empresa no DoneTalk (o mesmo da chave).

Parâmetros de consulta

Campo	Tipo	Obrigatório	Detalhes
`view`	um de `mine`, `team`, `queue`, `waiting_contact`, `snoozed`, `closed`, `mentions`, `all`	não	default `"mine"`
`limit`	integer	não	até 100; mínimo 1; default `50`
`before`	string (date-time)	não
`q`	string	não	até 200 caracteres
`tag`	string (uuid)	não

Exemplo de pedido

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

Resposta 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"
      }
    }
  ]
}

Erros possíveis

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Abrir um atendimento por modelo

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

Para um contato já cadastrado. assigneeMemberId escolhe quem atende; sem ele, o atendimento espera a resposta e entra na fila da equipe.

Parâmetros do endereço

Campo	Detalhes
`slug`	O identificador da empresa no DoneTalk (o mesmo da chave).

Corpo do pedido

Campo	Tipo	Obrigatório	Detalhes
`contactId`	string (uuid)	sim
`channelId`	string (uuid)	não
`templateId`	string (uuid)	sim
`parameters`	object	não	default `{}`
`headerUploadId`	string (uuid)	não
`headerLink`	string (uri)	não	até 2000 caracteres
`teamId`	string (uuid)	não	null
`goal`	string	não	até 60 caracteres
`assigneeMemberId`	string (uuid)	não

Exemplo de pedido

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"
  }
}'

Resposta 201

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

Erros possíveis

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

Ver um atendimento

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

O atendimento com as mensagens, os eventos (atribuições, transferências) e, quando concluído, o desfecho.

Parâmetros do endereço

Campo	Detalhes
`slug`	O identificador da empresa no DoneTalk (o mesmo da chave).
`id`	O id do registro.

Exemplo de pedido

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

Resposta 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": []
}

Erros possíveis

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Mandar uma mensagem no atendimento

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

type: template com o escopo messages:send_template. text e media (arquivo de POST /uploads) pedem messages:send_text e a janela de 24 horas aberta.

Parâmetros do endereço

Campo	Detalhes
`slug`	O identificador da empresa no DoneTalk (o mesmo da chave).
`id`	O id do registro.

Corpo do pedido

Campo	Tipo	Obrigatório	Detalhes
`type`	um de `text`	sim
`text`	string	sim	até 4096 caracteres
`replyToProviderMessageId`	string	não
`linkPreview`	boolean	não
`gateDecisionId`	string (uuid)	não
`gateAction`	um de `accepted`, `edited`, `overridden`	não
`templateId`	string (uuid)	sim
`parameters`	object	não	default `{}`
`headerUploadId`	string (uuid)	não
`headerLink`	string (uri)	não	até 2000 caracteres
`uploadId`	string (uuid)	sim
`caption`	string	não	até 1024 caracteres
`contactIds`	lista de string (uuid)	sim	até 10

Exemplo de pedido

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."
}'

Resposta 202

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

Erros possíveis

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

Concluir com um desfecho

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

outcomeCode vem de GET /outcomes. Com ifNoReplyHours, conclui só se o contato não responder nesse prazo.

Parâmetros do endereço

Campo	Detalhes
`slug`	O identificador da empresa no DoneTalk (o mesmo da chave).
`id`	O id do registro.

Corpo do pedido

Campo	Tipo	Obrigatório	Detalhes
`outcomeCode`	string	sim	até 60 caracteres
`note`	string	não	até 4000 caracteres
`ifNoReplyHours`	integer	não	até 720; mínimo 1

Exemplo de pedido

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."
}'

Resposta 200

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

Erros possíveis

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Reabrir

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

Parâmetros do endereço

Campo	Detalhes
`slug`	O identificador da empresa no DoneTalk (o mesmo da chave).
`id`	O id do registro.

Exemplo de pedido

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

Resposta 200

{
  "ok": true
}

Erros possíveis

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Enviar um arquivo

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

multipart/form-data com o campo file (e intent: media, document, audio, sticker). Devolve o id para mandar numa mensagem ou pôr no cabeçalho de uma campanha.

Parâmetros do endereço

Campo	Detalhes
`slug`	O identificador da empresa no DoneTalk (o mesmo da chave).

Corpo do pedido

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

Exemplo de pedido

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

Resposta 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
  }
}

Erros possíveis

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Esta página em Markdown