Contatos

Na TopTalking, um contato é uma conversa da caixa de entrada: um por número de telefone e canal. O contato guarda os dados da pessoa (nome, telefone, e-mail) e o estado do atendimento (etapa do Kanban, responsável, agente de IA, fixada, finalizada, arquivada).

Grupos também são conversas: aparecem aqui com is_group: true, e o id do grupo funciona em todos os endpoints desta página.

O objeto contato

{
  "id": "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60",
  "object": "contact",
  "name": "Maria Souza",
  "phone": "5511999998888",
  "email": "maria@exemplo.com",
  "channel_id": "d781e759-4047-4c35-bfcd-eae8c666369a",
  "channel_type": "whatsapp",
  "is_group": false,
  "stage": {
    "id": "9b2f5a8e-6a3b-4d0e-9a51-2a7f4f1d0c11",
    "name": "Negociação",
    "is_final": false
  },
  "ai_enabled": true,
  "ai_agent_id": null,
  "assigned_to": "4083deb8-f96e-4093-8598-ebdd4dee786b",
  "pinned": false,
  "unread_count": 2,
  "last_message_at": "2026-11-11T14:12:40Z",
  "last_message_preview": "Vocês entregam no sábado?",
  "resolved_at": null,
  "archived_at": null,
  "source": "whatsapp",
  "created_at": "2026-10-28T19:03:55Z",
  "updated_at": "2026-11-11T14:12:40Z"
}

Campo	Tipo	Descrição
`id`	UUID	ID do contato (da conversa).
`object`	string	Sempre `contact`.
`name`	string ou `null`	Nome do contato (ou do grupo).
`phone`	string ou `null`	Telefone só com dígitos, com DDI (ex.: `5511999998888`). `null` em grupos e em conversas do Chat do site sem telefone.
`email`	string ou `null`	E-mail.
`channel_id`	UUID ou `null`	Canal da conversa.
`channel_type`	string	`whatsapp` ou `webchat` (Chat do site).
`is_group`	booleano	Grupo de WhatsApp. Grupos não têm IA, mas recebem mensagens pela API (veja Grupos).
`stage`	objeto ou `null`	Etapa atual no Kanban (`id`, `name`, `is_final`), ou `null` se não está em nenhuma.
`ai_enabled`	booleano	Se a IA responde esta conversa.
`ai_agent_id`	UUID ou `null`	Agente de IA da conversa. `null` = o agente padrão.
`assigned_to`	UUID ou `null`	Membro responsável pela conversa. `null` = sem responsável.
`pinned`	booleano	Conversa fixada no topo da caixa de entrada.
`unread_count`	inteiro	Mensagens não lidas no painel.
`last_message_at`	data ou `null`	Data da última mensagem.
`last_message_preview`	string ou `null`	Prévia da última mensagem.
`resolved_at`	data ou `null`	Quando a conversa foi finalizada (`null` = em aberto).
`archived_at`	data ou `null`	Quando a conversa foi arquivada (`null` = ativa).
`source`	string	Origem do contato: `whatsapp`, `webchat`, `api`, `agenda`, `lead`…
`created_at`	data	Criação.
`updated_at`	data	Última alteração.

Listar contatos

GET/v1/contacts

Lista as conversas ordenadas pela última mensagem (mais recentes primeiro). Use para buscar um contato, montar a sua caixa de entrada, ler um quadro do Kanban ou a fila de um atendente. Todos os filtros são opcionais e podem ser combinados.

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`search`	query	string	não	Busca parcial por nome ou telefone (até 100 caracteres).
`phone`	query	string	não	Telefone exato. Aceita formatado (`+55 11 99999-8888`); é normalizado para dígitos.
`stage_id`	query	UUID	não	Só contatos nesta etapa do Kanban.
`channel_id`	query	UUID	não	Só contatos deste canal.
`archived`	query	booleano	não	`true` só arquivados, `false` só ativos. Sem o parâmetro, todos.
`is_group`	query	booleano	não	`false` só conversas individuais, `true` só grupos. Sem o parâmetro, todos.
`assigned_to`	query	string	não	ID do membro responsável, ou `none` para conversas sem responsável.
`limit`	query	inteiro	não	Itens por página, 1 a 100 (padrão 20).
`cursor`	query	string	não	`next_cursor` da página anterior. Veja Paginação.

# Conversas individuais ativas na etapa "Negociação"
curl "https://platform.toptalking.com.br/v1/contacts?stage_id=9b2f5a8e-6a3b-4d0e-9a51-2a7f4f1d0c11&archived=false&is_group=false&limit=50" \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

# Procurar um contato pelo telefone
curl "https://platform.toptalking.com.br/v1/contacts?phone=5511999998888" \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

# Conversas sem responsável
curl "https://platform.toptalking.com.br/v1/contacts?assigned_to=none&archived=false" \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

const url = new URL('https://platform.toptalking.com.br/v1/contacts');
url.searchParams.set('search', 'maria');
url.searchParams.set('archived', 'false');
url.searchParams.set('is_group', 'false');

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}` },
});
const { data: contatos, has_more, next_cursor } = await res.json();

import os
import requests

res = requests.get(
    "https://platform.toptalking.com.br/v1/contacts",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    params={"search": "maria", "archived": "false", "is_group": "false"},
    timeout=30,
)
res.raise_for_status()
pagina = res.json()
contatos = pagina["data"]

Resposta `200`

{
  "object": "list",
  "data": [
    {
      "id": "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60",
      "object": "contact",
      "name": "Maria Souza",
      "phone": "5511999998888",
      "email": "maria@exemplo.com",
      "channel_id": "d781e759-4047-4c35-bfcd-eae8c666369a",
      "channel_type": "whatsapp",
      "is_group": false,
      "stage": {
        "id": "9b2f5a8e-6a3b-4d0e-9a51-2a7f4f1d0c11",
        "name": "Negociação",
        "is_final": false
      },
      "ai_enabled": true,
      "ai_agent_id": null,
      "assigned_to": "4083deb8-f96e-4093-8598-ebdd4dee786b",
      "pinned": false,
      "unread_count": 2,
      "last_message_at": "2026-11-11T14:12:40Z",
      "last_message_preview": "Vocês entregam no sábado?",
      "resolved_at": null,
      "archived_at": null,
      "source": "whatsapp",
      "created_at": "2026-10-28T19:03:55Z",
      "updated_at": "2026-11-11T14:12:40Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0xMS0xMVQxNDoxMjo0MFoifQ"
}

Erros

HTTP	`code`	Quando acontece
401	`missing_api_key`, `invalid_api_key`…	Problema com a chave. Veja Autenticação.

Criar ou atualizar contato

POST/v1/contacts

Cria o contato pelo telefone. Se já existir um contato com esse telefone na organização, os campos enviados são atualizados e a resposta é 200 em vez de 201 — então dá para chamar sem verificar antes (“upsert”). Ideal para formulários de lead e sincronização com o seu CRM.

O contato criado aparece na caixa de entrada do painel. Para já colocá-lo no funil, envie stage_id. Como há um contato por número e canal, quando o telefone existe em mais de um canal é atualizada a conversa do channel_id informado ou, sem ele, a que teve mensagem mais recente.

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`phone`	corpo	string	sim	Telefone com DDI e DDD. Formatação é ignorada; números brasileiros sem `55` recebem o `55`.
`name`	corpo	string	não	Nome (até 120 caracteres).
`email`	corpo	string	não	E-mail.
`stage_id`	corpo	UUID	não	Já coloca o card nesta etapa do Kanban. Veja `GET /stages`.
`channel_id`	corpo	UUID	não	Canal de WhatsApp da conversa. Padrão: o WhatsApp principal.
`Idempotency-Key`	cabeçalho	string	não	Para retentativas seguras. Veja Idempotência.

curl https://platform.toptalking.com.br/v1/contacts \
  -H "Authorization: Bearer $TOPTALKING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lead-5511999998888" \
  -d '{
    "phone": "+55 11 99999-8888",
    "name": "Maria Souza",
    "email": "maria@exemplo.com",
    "stage_id": "e63d8231-3992-457e-a8b0-d1be2fa591d4"
  }'

const res = await fetch('https://platform.toptalking.com.br/v1/contacts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'lead-5511999998888',
  },
  body: JSON.stringify({
    phone: '+55 11 99999-8888',
    name: 'Maria Souza',
    email: 'maria@exemplo.com',
    stage_id: 'e63d8231-3992-457e-a8b0-d1be2fa591d4', // "Novo lead"
  }),
});
const contato = await res.json();
console.log(res.status === 201 ? 'Contato criado' : 'Contato atualizado', contato.id);

import os
import requests

res = requests.post(
    "https://platform.toptalking.com.br/v1/contacts",
    headers={
        "Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}",
        "Idempotency-Key": "lead-5511999998888",
    },
    json={
        "phone": "+55 11 99999-8888",
        "name": "Maria Souza",
        "email": "maria@exemplo.com",
        "stage_id": "e63d8231-3992-457e-a8b0-d1be2fa591d4",  # "Novo lead"
    },
    timeout=30,
)
contato = res.json()
print("Contato criado" if res.status_code == 201 else "Contato atualizado", contato["id"])

Resposta `201` (criado) ou `200` (já existia)

{
  "id": "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60",
  "object": "contact",
  "name": "Maria Souza",
  "phone": "5511999998888",
  "email": "maria@exemplo.com",
  "channel_id": "d781e759-4047-4c35-bfcd-eae8c666369a",
  "channel_type": "whatsapp",
  "is_group": false,
  "stage": {
    "id": "e63d8231-3992-457e-a8b0-d1be2fa591d4",
    "name": "Novo lead",
    "is_final": false
  },
  "ai_enabled": true,
  "ai_agent_id": null,
  "assigned_to": null,
  "pinned": false,
  "unread_count": 0,
  "last_message_at": null,
  "last_message_preview": null,
  "resolved_at": null,
  "archived_at": null,
  "source": "api",
  "created_at": "2026-11-11T14:20:05Z",
  "updated_at": "2026-11-11T14:20:05Z"
}

Erros

HTTP	`code`	Quando acontece
400	`missing_field`	Faltou `phone`.
400	`invalid_phone`	Telefone inválido.
400	`invalid_field`	Algum campo inválido (ex.: `email`, `stage_id` que não é etapa da organização ou `name` longo demais).
403	`read_only_key`	Chave somente leitura.
404	`resource_not_found`	`channel_id` não encontrado.
409	`idempotency_conflict`	`Idempotency-Key` reutilizada com outro corpo.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_phone",
    "message": "Telefone inválido. Envie com DDI e DDD, ex.: 5511999998888.",
    "param": "phone",
    "request_id": "req_6f1d2c3b4a5e"
  }
}

Buscar contato

GET/v1/contacts/{contact_id}

Um contato pelo ID — por exemplo, o contact_id que chegou num webhook ou numa mensagem.

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`contact_id`	caminho	UUID	sim	ID do contato (ou do grupo).

curl https://platform.toptalking.com.br/v1/contacts/3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60 \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

const contactId = '3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60';
const res = await fetch(`https://platform.toptalking.com.br/v1/contacts/${contactId}`, {
  headers: { Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}` },
});
const contato = await res.json();

import os
import requests

contact_id = "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60"
res = requests.get(
    f"https://platform.toptalking.com.br/v1/contacts/{contact_id}",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    timeout=30,
)
res.raise_for_status()
contato = res.json()

Resposta `200`

O objeto contato:

{
  "id": "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60",
  "object": "contact",
  "name": "Maria Souza",
  "phone": "5511999998888",
  "email": "maria@exemplo.com",
  "channel_id": "d781e759-4047-4c35-bfcd-eae8c666369a",
  "channel_type": "whatsapp",
  "is_group": false,
  "stage": {
    "id": "9b2f5a8e-6a3b-4d0e-9a51-2a7f4f1d0c11",
    "name": "Negociação",
    "is_final": false
  },
  "ai_enabled": true,
  "ai_agent_id": null,
  "assigned_to": "4083deb8-f96e-4093-8598-ebdd4dee786b",
  "pinned": false,
  "unread_count": 2,
  "last_message_at": "2026-11-11T14:12:40Z",
  "last_message_preview": "Vocês entregam no sábado?",
  "resolved_at": null,
  "archived_at": null,
  "source": "whatsapp",
  "created_at": "2026-10-28T19:03:55Z",
  "updated_at": "2026-11-11T14:12:40Z"
}

Erros

HTTP	`code`	Quando acontece
404	`resource_not_found`	O contato não existe (ex.: foi apagado no painel) ou é de outra organização.

Atualizar contato (e mover no Kanban)

PATCH/v1/contacts/{contact_id}

Envie só os campos que quer mudar. É com este endpoint que você:

move o card no Kanban (stage_id);
atribui a conversa a um atendente (assigned_to) — veja Equipe;
liga ou desliga a IA naquela conversa (ai_enabled) ou troca o agente (ai_agent_id) — veja Agentes de IA;
fixa a conversa no topo (pinned);
finaliza ou reabre a conversa (resolved);
arquiva ou desarquiva (archived);
corrige nome e e-mail.

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`contact_id`	caminho	UUID	sim	ID do contato (ou do grupo).
`name`	corpo	string	não	Nome (até 120 caracteres).
`email`	corpo	string ou `null`	não	E-mail. `null` apaga.
`stage_id`	corpo	UUID ou `null`	não	Move o card para esta etapa. `null` tira o card de qualquer etapa. Mover para a etapa final (`is_final: true`) também finaliza a conversa, igual ao painel.
`assigned_to`	corpo	UUID ou `null`	não	Membro responsável (veja `GET /members`). `null` libera a conversa.
`ai_enabled`	corpo	booleano	não	`true` liga e `false` desliga a IA nesta conversa.
`ai_agent_id`	corpo	UUID ou `null`	não	Agente de IA desta conversa (veja `GET /ai-agents`). `null` volta para o agente padrão.
`pinned`	corpo	booleano	não	`true` fixa a conversa no topo da caixa de entrada; `false` desafixa.
`resolved`	corpo	booleano	não	`true` finaliza a conversa; `false` reabre.
`archived`	corpo	booleano	não	`true` arquiva; `false` desarquiva.

# Mover para a etapa "Negociação"
curl -X PATCH https://platform.toptalking.com.br/v1/contacts/3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60 \
  -H "Authorization: Bearer $TOPTALKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "stage_id": "9b2f5a8e-6a3b-4d0e-9a51-2a7f4f1d0c11" }'

# Um humano vai assumir: desligar a IA, atribuir à Carla e fixar
curl -X PATCH https://platform.toptalking.com.br/v1/contacts/3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60 \
  -H "Authorization: Bearer $TOPTALKING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ai_enabled": false, "assigned_to": "4083deb8-f96e-4093-8598-ebdd4dee786b", "pinned": true }'

async function atualizarContato(contactId, campos) {
  const res = await fetch(`https://platform.toptalking.com.br/v1/contacts/${contactId}`, {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(campos),
  });
  const body = await res.json();
  if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  return body;
}

// Mover no Kanban
await atualizarContato('3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60', {
  stage_id: '9b2f5a8e-6a3b-4d0e-9a51-2a7f4f1d0c11',
});

// Passar para o agente de IA "Vendas"
await atualizarContato('3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60', {
  ai_agent_id: '52da47ff-662a-4292-9961-27a95fc5ddd8',
});

// Finalizar a conversa
await atualizarContato('3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60', { resolved: true });

import os
import requests


def atualizar_contato(contact_id: str, campos: dict) -> dict:
    res = requests.patch(
        f"https://platform.toptalking.com.br/v1/contacts/{contact_id}",
        headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
        json=campos,
        timeout=30,
    )
    body = res.json()
    if not res.ok:
        raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
    return body


# Um humano vai assumir: desligar a IA, atribuir à Carla e fixar
atualizar_contato(
    "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60",
    {"ai_enabled": False, "assigned_to": "4083deb8-f96e-4093-8598-ebdd4dee786b", "pinned": True},
)

Resposta `200`

O contato atualizado (aqui, depois do segundo exemplo em curl):

{
  "id": "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60",
  "object": "contact",
  "name": "Maria Souza",
  "phone": "5511999998888",
  "email": "maria@exemplo.com",
  "channel_id": "d781e759-4047-4c35-bfcd-eae8c666369a",
  "channel_type": "whatsapp",
  "is_group": false,
  "stage": {
    "id": "9b2f5a8e-6a3b-4d0e-9a51-2a7f4f1d0c11",
    "name": "Negociação",
    "is_final": false
  },
  "ai_enabled": false,
  "ai_agent_id": null,
  "assigned_to": "4083deb8-f96e-4093-8598-ebdd4dee786b",
  "pinned": true,
  "unread_count": 2,
  "last_message_at": "2026-11-11T14:12:40Z",
  "last_message_preview": "Vocês entregam no sábado?",
  "resolved_at": null,
  "archived_at": null,
  "source": "whatsapp",
  "created_at": "2026-10-28T19:03:55Z",
  "updated_at": "2026-11-11T14:35:21Z"
}

Erros

HTTP	`code`	Quando acontece
400	`missing_field`	O corpo não tem nenhum campo para atualizar.
400	`invalid_json`, `invalid_field`	Corpo inválido ou campo com valor inválido: `stage_id` que não é etapa da organização, `assigned_to` que não é membro, `ai_agent_id` que não é agente da organização… (`param` diz qual).
403	`read_only_key`	Chave somente leitura.
404	`resource_not_found`	O contato não existe.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_field",
    "message": "Este usuário não é membro da organização. Veja GET /v1/members.",
    "param": "assigned_to",
    "request_id": "req_6f1d2c3b4a5e"
  }
}

Cada alteração de nome, e-mail, etapa, responsável, IA, arquivamento ou finalização dispara o webhook contact.updated e, se a etapa mudou, contact.stage_changed.

Marcar conversa como lida

POST/v1/contacts/{contact_id}/read

Zera o contador de não lidas (unread_count) da conversa no painel. Use quando o seu sistema (ou a sua IA) já tratou as mensagens novas, para a equipe não abrir a conversa à toa.

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`contact_id`	caminho	UUID	sim	ID do contato (ou do grupo).

curl -X POST https://platform.toptalking.com.br/v1/contacts/3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60/read \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

const contactId = '3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60';
const res = await fetch(`https://platform.toptalking.com.br/v1/contacts/${contactId}/read`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}` },
});
const contato = await res.json(); // contato.unread_count === 0

import os
import requests

contact_id = "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60"
res = requests.post(
    f"https://platform.toptalking.com.br/v1/contacts/{contact_id}/read",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    timeout=30,
)
res.raise_for_status()

Resposta `200`

O contato, com unread_count: 0:

{
  "id": "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60",
  "object": "contact",
  "name": "Maria Souza",
  "phone": "5511999998888",
  "email": "maria@exemplo.com",
  "channel_id": "d781e759-4047-4c35-bfcd-eae8c666369a",
  "channel_type": "whatsapp",
  "is_group": false,
  "stage": {
    "id": "9b2f5a8e-6a3b-4d0e-9a51-2a7f4f1d0c11",
    "name": "Negociação",
    "is_final": false
  },
  "ai_enabled": true,
  "ai_agent_id": null,
  "assigned_to": "4083deb8-f96e-4093-8598-ebdd4dee786b",
  "pinned": false,
  "unread_count": 0,
  "last_message_at": "2026-11-11T14:12:40Z",
  "last_message_preview": "Vocês entregam no sábado?",
  "resolved_at": null,
  "archived_at": null,
  "source": "whatsapp",
  "created_at": "2026-10-28T19:03:55Z",
  "updated_at": "2026-11-11T14:13:02Z"
}

Erros

HTTP	`code`	Quando acontece
403	`read_only_key`	Chave somente leitura.
404	`resource_not_found`	O contato não existe.

Histórico da conversa

GET/v1/contacts/{contact_id}/messages

Mensagens da conversa, das mais recentes para as mais antigas, com paginação. Use para mostrar a conversa no seu sistema ou dar contexto a uma IA. Funciona também para grupos (com o id do grupo). Mensagens apagadas com scope=me não aparecem.

Parâmetro	Onde	Tipo	Obrigatório	Descrição
`contact_id`	caminho	UUID	sim	ID do contato (ou do grupo).
`limit`	query	inteiro	não	Itens por página, 1 a 100 (padrão 20).
`cursor`	query	string	não	`next_cursor` da página anterior.

curl "https://platform.toptalking.com.br/v1/contacts/3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60/messages?limit=50" \
  -H "Authorization: Bearer $TOPTALKING_API_KEY"

const contactId = '3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60';
const res = await fetch(
  `https://platform.toptalking.com.br/v1/contacts/${contactId}/messages?limit=50`,
  { headers: { Authorization: `Bearer ${process.env.TOPTALKING_API_KEY}` } },
);
const { data: mensagens } = await res.json();
// Para exibir em ordem cronológica:
const conversa = [...mensagens].reverse();

import os
import requests

contact_id = "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60"
res = requests.get(
    f"https://platform.toptalking.com.br/v1/contacts/{contact_id}/messages",
    headers={"Authorization": f"Bearer {os.environ['TOPTALKING_API_KEY']}"},
    params={"limit": 50},
    timeout=30,
)
res.raise_for_status()
conversa = list(reversed(res.json()["data"]))  # ordem cronológica

Resposta `200`

{
  "object": "list",
  "data": [
    {
      "id": "b7fa4c19-3e25-4ce9-9794-4e7f60efa4ba",
      "object": "message",
      "contact_id": "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60",
      "channel_id": "d781e759-4047-4c35-bfcd-eae8c666369a",
      "direction": "inbound",
      "type": "text",
      "text": "Vocês entregam no sábado?",
      "media": null,
      "status": "delivered",
      "error": null,
      "reply_to_id": null,
      "reaction": null,
      "sender_name": null,
      "transcript": null,
      "created_at": "2026-11-11T14:12:40Z",
      "edited_at": null
    },
    {
      "id": "a9d91e32-912f-4866-b018-e7c4cfe7f45b",
      "object": "message",
      "contact_id": "3f1c2b9a-7d4e-4c55-8a0e-1b2c3d4e5f60",
      "channel_id": "d781e759-4047-4c35-bfcd-eae8c666369a",
      "direction": "outbound",
      "type": "text",
      "text": "Oi, Maria! Recebemos o seu pedido #1234 e ele já está sendo separado. 😊",
      "media": null,
      "status": "read",
      "error": null,
      "reply_to_id": null,
      "reaction": null,
      "sender_name": null,
      "transcript": null,
      "created_at": "2026-11-11T14:05:02Z",
      "edited_at": null
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0xMS0xMVQxNDowNTowMloifQ"
}

O formato de cada item é o objeto mensagem.

Erros

HTTP	`code`	Quando acontece
404	`resource_not_found`	O contato não existe.

Contatos

O objeto contato

Listar contatos

Resposta 200

Erros

Criar ou atualizar contato

Resposta 201 (criado) ou 200 (já existia)

Erros

Buscar contato

Resposta 200

Erros

Atualizar contato (e mover no Kanban)

Resposta 200

Erros

Marcar conversa como lida

Resposta 200

Erros

Histórico da conversa

Resposta 200

Erros

Resposta `200`

Resposta `201` (criado) ou `200` (já existia)

Resposta `200`

Resposta `200`

Resposta `200`

Resposta `200`