Chats

Com a API de chats você pode gerenciar as conversas da sua empresa, incluindo listagem e transferência entre canais e atendentes.

Listar Chats

GET https://api.tinko.com.br/v1/chats

Retorna todos os chats (conversas) da empresa autenticada, incluindo informações do contato e a última mensagem.

Headers

Nome	Tipo	Obrigatório	Descrição
Authorization	string	Sim	Token de autenticação. Ex: `Bearer seu_token`

Query Parameters

Nome	Tipo	Obrigatório	Descrição
page	integer	Não	Número da página. Default: `1`
per_page	integer	Não	Registros por página (máx: 100). Default: `20`
status	string	Não	Filtrar por status: `entrance`, `waiting`, `finished`. Default: `todos`
is_open	boolean	Não	Filtrar por chats abertos ou fechados. Default: `todos`
contact	string	Não	Filtrar por ID ou telefone do contato. Default: `todos`
tag	string	Não	Filtrar por ID da tag. Default: `todos`
channel	string	Não	Filtrar por ID do canal. Default: `todos`
attendant	string	Não	Filtrar por ID do atendente. Default: `todos`

Exemplo de requisição

curl -X GET "https://api.tinko.com.br/v1/chats?status=waiting&is_open=true" \
  -H "Authorization: Bearer SEU_TOKEN"

Response

{
  "success": true,
  "data": [
    {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "is_open": true,
      "status": "waiting",
      "unreadCount": 3,
      "contact": {
        "id": "01hxyz123abc456def789ghjkm",
        "name": "João Silva",
        "phone": "5511999999999"
      },
      "lastMessage": {
        "id": "01j7m8n9p0q1r2s3t4u5v6w7x",
        "content": "Olá, preciso de ajuda!",
        "created_at": "2025-10-29T10:30:00.000000Z"
      }
    }
  ],
  "pagination": {
    "total": 15,
    "per_page": 20,
    "current_page": 1,
    "last_page": 1
  }
}

Campos do Response

Campo	Tipo	Descrição
id	string	ID do chat
is_open	boolean	Se o chat está aberto (`true`) ou fechado (`false`)
status	string	Status: `entrance` (última mensagem foi nossa), `waiting` (última mensagem foi do contato), `finished` (atendimento finalizado, não recebe novas mensagens)
unreadCount	integer	Quantidade de mensagens não lidas
contact	object	Dados do contato vinculado
lastMessage	object	Última mensagem enviada

Transferir Chat

POST https://api.tinko.com.br/v1/chats/{id}/transfer

Transfere uma conversa para outro canal ou atendente. Você pode transferir apenas entre canais, apenas entre atendentes, ou ambos.

Campo	Tipo	Obrigatório	Descrição
channel	string	Sim	ID do canal de destino
attendant	string	Não	ID do atendente de destino. Se não informado, vai para a fila de espera
message	string	Não	Mensagem interna de contexto (máx: 1000 caracteres). Visível apenas para a equipe

Exemplo de requisição

curl -X POST "https://api.tinko.com.br/v1/chats/01arz3ndektsv4rrffq69g5fav/transfer" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "01hxyz123abc456def789ghjkm",
    "attendant": "01j7m8n9p0q1r2s3t4u5v6w7x",
    "message": "Cliente precisa falar sobre reembolso. Pedido #12345."
  }'

Response

{
  "success": true,
  "message": "Conversa transferida com sucesso.",
  "data": {
    "chat": "01arz3ndektsv4rrffq69g5fav",
    "channel": "01hxyz123abc456def789ghjkm",
    "attendant": "01j7m8n9p0q1r2s3t4u5v6w7x"
  }
}

Erros

{
  "success": false,
  "message": "Conversa ou canal não encontrado."
}

{
  "success": false,
  "message": "Você não tem permissão para transferir conversas deste canal."
}

{
  "success": false,
  "message": "O atendente informado não tem acesso ao canal de destino."
}

Como funciona

Transferência no mesmo canal: Apenas troca o atendente responsável. O chat permanece o mesmo, mantendo todo o histórico.

Transferência para outro canal: Cria um novo chat no canal de destino, vincula o mesmo contato e inclui um link para o chat original.