Mensagens

Com a API de mensagens você pode enviar mensagens e consultar o histórico de um chat.

Se você só precisa listar e transferir conversas, veja: Chats.

Listar Mensagens

GET https://api.tinko.com.br/v1/chats/{id}/messages

Retorna todas as mensagens de um chat específico.

Headers

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

Path Parameters

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	ID do chat

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
type	string	Não	Filtrar por tipo: text, image, video, audio, document, sticker, vcard, template. Default: todos
direction	string	Não	Filtrar por direção: incoming (recebida), outgoing (enviada). Default: todos
visibility	string	Não	Filtrar por visibilidade: client (visível), internal (nota interna). Default: todos
attendant	string	Não	Filtrar por ID do atendente. Default: todos
content	string	Não	Buscar no conteúdo da mensagem (busca parcial)

Exemplo de requisição

curl -X GET "https://api.tinko.com.br/v1/chats/01arz3ndektsv4rrffq69g5fav/messages?direction=incoming&type=text" \
  -H "Authorization: Bearer SEU_TOKEN"

Response

{
  "success": true,
  "data": [
    {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "signature": null,
      "content": "Oi",
      "type": "text",
      "direction": "incoming",
      "visibility": "client",
      "created_at": "2025-10-29T17:58:47.000000Z",
      "is_forwarded": false,
      "user": null,
      "file": null
    },
    {
      "id": "01hxyz123abc456def789ghjkm",
      "signature": "João Silva",
      "content": "oi",
      "type": "text",
      "direction": "outgoing",
      "visibility": "client",
      "created_at": "2025-10-29T17:58:36.000000Z",
      "is_forwarded": false,
      "user": {
        "id": "01j7m8n9p0q1r2s3t4u5v6w7x",
        "name": "João Silva",
        "email": "joao.silva@exemplo.com.br",
        "type": "admin"
      },
      "file": null
    }
  ],
  "pagination": {
    "total": 2,
    "per_page": 20,
    "current_page": 1,
    "last_page": 1
  }
}

Campos do Response

Campo	Tipo	Descrição
id	string	ID da mensagem
signature	string/null	Assinatura do atendente
content	string	Conteúdo da mensagem
type	string	Tipo: text, image, video, audio, document, sticker, vcard, template
direction	string	incoming (recebida) ou outgoing (enviada)
visibility	string	client (visível) ou internal (nota interna)
is_forwarded	boolean	Se foi encaminhada
user	object/null	Usuário que enviou (apenas outgoing)
file	object/null	Arquivo anexado

Enviar Mensagem

POST https://api.tinko.com.br/v1/messages

Envia uma mensagem para um contato. Suporta texto, mídia e templates.

Headers

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

Request Body

Nome	Tipo	Obrigatório	Descrição
phone	string	Sim	Número do destinatário com código do país. Ex: 5511999999999
channel	string	Sim	ID do canal que enviará a mensagem
attendant	string	Não	ID do atendente a ser vinculado à mensagem
type	string	Não	Tipo: text, image, video, audio, document, sticker, vcard, template. Default: text
content	string	Condicional	Conteúdo da mensagem. Obrigatório para type: text
path	string	Condicional	URL pública do arquivo. Obrigatório para tipos de mídia
caption	string	Não	Legenda do arquivo (para mídia)
name	string	Condicional	Nome do contato. Obrigatório para type: vcard
contact	string	Condicional	Telefone do contato. Obrigatório para type: vcard
template	string	Condicional	ID do template. Obrigatório para type: template
components	array	Condicional	Componentes com variáveis. Obrigatório para type: template

Tipos de Envio

---

Mensagem de texto

POST https://api.tinko.com.br/v1/messages

Envia uma mensagem de texto simples para o contato.

Campo	Tipo	Obrigatório	Descrição
phone	string	Sim	Número do destinatário com código do país
channel	string	Sim	ID do canal que enviará a mensagem
attendant	string	Não	ID do atendente a ser vinculado à mensagem
type	string	Sim	text
content	string	Sim	Conteúdo da mensagem

curl -X POST "https://api.tinko.com.br/v1/messages" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "channel": "01arz3ndektsv4rrffq69g5fav",
    "content": "Olá! Como posso ajudar você hoje?",
    "type": "text"
  }'

---

Imagem

POST https://api.tinko.com.br/v1/messages

Envia uma imagem para o contato. Formatos suportados: JPG, JPEG, PNG.

Campo	Tipo	Obrigatório	Descrição
phone	string	Sim	Número do destinatário com código do país
channel	string	Sim	ID do canal que enviará a mensagem
attendant	string	Não	ID do atendente a ser vinculado à mensagem
type	string	Sim	image
path	string	Sim	URL pública da imagem
caption	string	Não	Legenda da imagem

curl -X POST "https://api.tinko.com.br/v1/messages" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "channel": "01arz3ndektsv4rrffq69g5fav",
    "path": "https://exemplo.com/produto.jpg",
    "caption": "Confira nossa promoção!",
    "type": "image"
  }'

---

Vídeo

POST https://api.tinko.com.br/v1/messages

Envia um vídeo para o contato. Formatos suportados: MP4.

Campo	Tipo	Obrigatório	Descrição
phone	string	Sim	Número do destinatário com código do país
channel	string	Sim	ID do canal que enviará a mensagem
attendant	string	Não	ID do atendente a ser vinculado à mensagem
type	string	Sim	video
path	string	Sim	URL pública do vídeo
caption	string	Não	Legenda do vídeo

curl -X POST "https://api.tinko.com.br/v1/messages" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "channel": "01arz3ndektsv4rrffq69g5fav",
    "path": "https://exemplo.com/video.mp4",
    "caption": "Tutorial do produto",
    "type": "video"
  }'

---

Áudio

POST https://api.tinko.com.br/v1/messages

Envia um áudio para o contato. Formatos suportados: MP3, OGG.

Campo	Tipo	Obrigatório	Descrição
phone	string	Sim	Número do destinatário com código do país
channel	string	Sim	ID do canal que enviará a mensagem
attendant	string	Não	ID do atendente a ser vinculado à mensagem
type	string	Sim	audio
path	string	Sim	URL pública do áudio

curl -X POST "https://api.tinko.com.br/v1/messages" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "channel": "01arz3ndektsv4rrffq69g5fav",
    "path": "https://exemplo.com/audio.mp3",
    "type": "audio"
  }'

---

Documento

POST https://api.tinko.com.br/v1/messages

Envia um documento para o contato. Formatos suportados: PDF, DOC, DOCX, XLS, XLSX, TXT, ZIP.

Campo	Tipo	Obrigatório	Descrição
phone	string	Sim	Número do destinatário com código do país
channel	string	Sim	ID do canal que enviará a mensagem
attendant	string	Não	ID do atendente a ser vinculado à mensagem
type	string	Sim	document
path	string	Sim	URL pública do documento
caption	string	Não	Legenda do documento

curl -X POST "https://api.tinko.com.br/v1/messages" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "channel": "01arz3ndektsv4rrffq69g5fav",
    "path": "https://exemplo.com/catalogo.pdf",
    "caption": "Catálogo de produtos 2025",
    "type": "document"
  }'

---

Sticker

POST https://api.tinko.com.br/v1/messages

Envia um sticker para o contato. Formato suportado: WEBP.

Campo	Tipo	Obrigatório	Descrição
phone	string	Sim	Número do destinatário com código do país
channel	string	Sim	ID do canal que enviará a mensagem
type	string	Sim	sticker
path	string	Sim	URL pública do sticker

curl -X POST "https://api.tinko.com.br/v1/messages" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "channel": "01arz3ndektsv4rrffq69g5fav",
    "path": "https://exemplo.com/sticker.webp",
    "type": "sticker"
  }'

---

Contato (vCard)

POST https://api.tinko.com.br/v1/messages

Envia um cartão de contato para o destinatário.

Campo	Tipo	Obrigatório	Descrição
phone	string	Sim	Número do destinatário com código do país
channel	string	Sim	ID do canal que enviará a mensagem
type	string	Sim	vcard
name	string	Sim	Nome do contato a ser compartilhado
contact	string	Sim	Telefone do contato a ser compartilhado

curl -X POST "https://api.tinko.com.br/v1/messages" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "channel": "01arz3ndektsv4rrffq69g5fav",
    "name": "João Silva",
    "contact": "+55 31 90000 0000",
    "type": "vcard"
  }'

---

Template (somente texto)

POST https://api.tinko.com.br/v1/messages

Envia um template de mensagem contendo apenas texto com variáveis.

Campo	Tipo	Obrigatório	Descrição
phone	string	Sim	Número do destinatário com código do país
channel	string	Sim	ID do canal que enviará a mensagem
type	string	Sim	template
template	string	Sim	ID do template cadastrado
components	array	Sim	Componentes com as variáveis do template

curl -X POST "https://api.tinko.com.br/v1/messages" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "channel": "01arz3ndektsv4rrffq69g5fav",
    "type": "template",
    "template": "01arz3ndektsv4rrffq69g5fav",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "João" },
          { "type": "text", "text": "BEMVINDO10" }
        ]
      }
    ]
  }'

---

Template com Header (imagem)

POST https://api.tinko.com.br/v1/messages

Envia um template de mensagem com imagem no cabeçalho e variáveis no corpo.

curl -X POST "https://api.tinko.com.br/v1/messages" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "channel": "01arz3ndektsv4rrffq69g5fav",
    "type": "template",
    "template": "01hxyz123abc456def789ghjkm",
    "components": [
      {
        "type": "header",
        "parameters": [
          { "type": "image", "path": "https://exemplo.com/pedido.jpg" }
        ]
      },
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "João" },
          { "type": "text", "text": "12345" },
          { "type": "text", "text": "25/12/2025" }
        ]
      }
    ]
  }'

---

Template com Botão Dinâmico

POST https://api.tinko.com.br/v1/messages

Envia um template de mensagem com botão de URL dinâmica.

curl -X POST "https://api.tinko.com.br/v1/messages" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "channel": "01arz3ndektsv4rrffq69g5fav",
    "type": "template",
    "template": "01j7m8n9p0q1r2s3t4u5v6w7x",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Carlos" },
          { "type": "text", "text": "98765" },
          { "type": "text", "text": "150,00" }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": 0,
        "parameters": [
          { "type": "text", "text": "ABC123XYZ" }
        ]
      }
    ]
  }'

Estrutura dos Componentes do Template

Campo	Tipo	Obrigatório	Descrição
type	string	Sim	Tipo: header, body, button
parameters	array	Sim	Lista de parâmetros/variáveis
sub_type	string	Condicional	Subtipo do botão: url, quick_reply. Obrigatório para type: button
index	integer	Condicional	Índice do botão, começando em 0. Obrigatório para type: button

Tipos de Parâmetros

Tipo	Campo	Descrição
text	text	Texto simples
image	path	URL pública de imagem
video	path	URL pública de vídeo
document	path	URL pública de documento

Response

{
  "success": true,
  "message": "Mensagem enviada com sucesso.",
  "data": {
    "message": {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "content": "Olá! Como posso ajudar você hoje?",
      "type": "text",
      "direction": "outgoing",
      "visibility": "client",
      "created_at": "2025-11-27T14:30:00.000000Z"
    },
    "chat": {
      "id": "01hxyz123abc456def789ghjkm",
      "status": "waiting",
      "is_open": true
    },
    "contact": {
      "phone": "5511999999999",
      "name": "João Silva"
    }
  }
}

Erros

Exemplo de erro estruturado:

{
  "success": false,
  "message": "Não foi possível enviar a mensagem.",
  "errors": [
    {
      "code": "CHANNEL_DISCONNECTED",
      "message": "O canal está desconectado. É necessário reconectar para enviar mensagens."
    }
  ]
}