Conversaciones

Listar conversaciones

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

Parámetros de la dirección

Campo	Detalles
`slug`	El identificador de la empresa en DoneTalk (el de la clave).

Parámetros de consulta

Campo	Tipo	Obligatorio	Detalles
`view`	uno de `mine`, `team`, `queue`, `waiting_contact`, `snoozed`, `closed`, `mentions`, `all`	no	default `"mine"`
`limit`	integer	no	hasta 100; mínimo 1; default `50`
`before`	string (date-time)	no
`q`	string	no	hasta 200 caracteres
`tag`	string (uuid)	no

Ejemplo de solicitud

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

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

Errores posibles

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Abrir una conversación con una plantilla

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

Para un contacto existente. assigneeMemberId elige quién atiende; sin él, espera la respuesta y entra en la cola del equipo.

Parámetros de la dirección

Campo	Detalles
`slug`	El identificador de la empresa en DoneTalk (el de la clave).

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Detalles
`contactId`	string (uuid)	sí
`channelId`	string (uuid)	no
`templateId`	string (uuid)	sí
`parameters`	object	no	default `{}`
`headerUploadId`	string (uuid)	no
`headerLink`	string (uri)	no	hasta 2000 caracteres
`teamId`	string (uuid)	no	null
`goal`	string	no	hasta 60 caracteres
`assigneeMemberId`	string (uuid)	no

Ejemplo de solicitud

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

Respuesta 201

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

Errores posibles

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

Ver una conversación

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

La conversación con sus mensajes, eventos (asignaciones, transferencias) y, al cerrarse, el desenlace.

Parámetros de la dirección

Campo	Detalles
`slug`	El identificador de la empresa en DoneTalk (el de la clave).
`id`	El id del registro.

Ejemplo de solicitud

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

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

Errores posibles

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Enviar un mensaje en la conversación

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

type: template con el alcance messages:send_template. text y media (archivo de POST /uploads) piden messages:send_text y la ventana de 24 horas abierta.

Parámetros de la dirección

Campo	Detalles
`slug`	El identificador de la empresa en DoneTalk (el de la clave).
`id`	El id del registro.

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Detalles
`type`	uno de `text`	sí
`text`	string	sí	hasta 4096 caracteres
`replyToProviderMessageId`	string	no
`linkPreview`	boolean	no
`gateDecisionId`	string (uuid)	no
`gateAction`	uno de `accepted`, `edited`, `overridden`	no
`templateId`	string (uuid)	sí
`parameters`	object	no	default `{}`
`headerUploadId`	string (uuid)	no
`headerLink`	string (uri)	no	hasta 2000 caracteres
`uploadId`	string (uuid)	sí
`caption`	string	no	hasta 1024 caracteres
`contactIds`	lista de string (uuid)	sí	hasta 10

Ejemplo de solicitud

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

Respuesta 202

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

Errores posibles

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

Concluir con un desenlace

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

outcomeCode viene de GET /outcomes. Con ifNoReplyHours, cierra solo si el contacto no responde en ese plazo.

Parámetros de la dirección

Campo	Detalles
`slug`	El identificador de la empresa en DoneTalk (el de la clave).
`id`	El id del registro.

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Detalles
`outcomeCode`	string	sí	hasta 60 caracteres
`note`	string	no	hasta 4000 caracteres
`ifNoReplyHours`	integer	no	hasta 720; mínimo 1

Ejemplo de solicitud

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

Respuesta 200

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

Errores posibles

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Reabrir

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

Parámetros de la dirección

Campo	Detalles
`slug`	El identificador de la empresa en DoneTalk (el de la clave).
`id`	El id del registro.

Ejemplo de solicitud

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

Respuesta 200

{
  "ok": true
}

Errores posibles

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Subir un archivo

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

multipart/form-data con el campo file (e intent: media, document, audio, sticker). Devuelve el id para enviar en un mensaje o poner en el encabezado de una campaña.

Parámetros de la dirección

Campo	Detalles
`slug`	El identificador de la empresa en DoneTalk (el de la clave).

Cuerpo de la solicitud

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

Ejemplo de solicitud

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

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

Errores posibles

401 unauthorized
403 insufficient_scope
422 validation_failed
429 rate_limited

Esta página en Markdown