Mensagens

Endpoints para enviar mensagens nos canais conectados da Plataforma Keeptor. V1 cobre WhatsApp. A arquitetura foi desenhada para incluir Email, Instagram e Telegram no futuro sem mudar essa API: o conteúdo é descrito de forma agnóstica ao canal e a Plataforma adapta o envio automaticamente.

Autenticação

Todas as rotas exigem Authorization: Bearer <access_token> (obtido via Login). Você só envia mensagens em conversas da sua própria organização.

Convenção de URL

Todas as URLs são prefixadas por:

• Produção: https://api.keeptor.com/prd/v1/omni/messages
• Homologação: https://api.keeptor.com/tst/v1/omni/messages

Estrutura de conteúdo: content_blocks

Toda mensagem é composta por um array de blocos de conteúdo (content_blocks). Cada bloco tem um campo type que define seu formato. Esse modelo permite descrever qualquer mensagem, de um texto simples a um carrossel interativo, com um único contrato, independente do canal de destino.

Exemplos de composição:

• Um WhatsApp com texto + foto → [ {type:"text"}, {type:"image"} ]
• Um carrossel → um único bloco {type:"carousel"} com os cards em items
• Uma resposta citando outra mensagem → o campo reply_to_message_id no envio

A Plataforma identifica o canal pela conversa informada (conversation_id) e adapta o envio. Você não precisa saber se a conversa é WhatsApp, Email ou outro canal: basta montar os blocos.

Catálogo de tipos de bloco

São 20 tipos de bloco. Nem todo canal suporta todos os tipos; a Plataforma valida a compatibilidade no momento do envio.

Capability matrix: a combinação de canal × tipo de bloco suportada é mantida pela Plataforma e exposta via /v1/dictionary. O cliente pode consultar quais tipos cada canal aceita antes de montar a mensagem.

Estados da mensagem (status_code)

Uma resposta 200 no envio significa apenas que a mensagem foi aceita e enfileirada (queued). A evolução do status (sent, delivered, read) chega de forma assíncrona.

Erros

Toda resposta de erro segue o schema ErrorResponse. Mostre ao usuário o message; para reconhecer o erro no seu código, use error.key, que não muda com o idioma nem com o texto. error.code está sempre presente; error.field aponta o campo que causou o erro (para exibir a mensagem embaixo dele); error.internal descreve a regra para o suporte. Exemplo real:

{
  "success": false,
  "message": "Conversa não encontrada.",
  "error": {
    "type": "NOT_FOUND",
    "code": "NOT_FOUND",
    "message": "Conversa não encontrada.",
    "key": "gateway.omni.messages.conversation_not_found",
    "params": {},
    "field": "conversation_id",
    "internal": "A conversa não existe ou não é da organização da sessão. Responde 404.",
    "fields": ["conversation_id"]
  }
}

Eventos em tempo real

Quando uma mensagem é enviada e quando seu status evolui, a Plataforma emite eventos em tempo real. O cliente assina o canal da conversa para receber as atualizações sem fazer polling.