Pular para o conteúdo principal
O endpoint sendMessageByTicket permite que você responda a qualquer conversa usando apenas o ID do ticket, sem precisar saber o canal subjacente ou o identificador do destinatário. Também é a única forma de enviar mensagens para conversas do Webchat e do Mercado Livre, que não possuem número de telefone endereçável nem ID externo persistente.

Visão Geral

Quando você já tem um ticketId vindo de um payload de webhook ou de uma chamada de API anterior, não precisa saber o canal subjacente: o endpoint sendMessageByTicket resolve o canal pelo próprio atendimento e roteia a mensagem para a conversa correta. Por isso, o token de qualquer API ativa da sua empresa serve para responder conversas de qualquer canal (WhatsApp, Instagram, Messenger, Telegram, Webchat, E-mail, Hub Notificame e Mercado Livre), mesmo que a API tenha sido criada para outro canal. Esta também é a única forma de enviar mensagens para conversas do Webchat e do Mercado Livre, já que esses canais não possuem número de telefone ou identificador persistente que você possa endereçar diretamente. URL Base
Autenticação
Endpoint

Conceitos-Chave

reopen

Se o ticket estiver fechado no momento, você deve definir reopen: true para reabri-lo antes que a mensagem possa ser entregue. Enviar para um ticket fechado sem essa flag retorna um erro 409 ERR_TICKET_CLOSED.

isClosed

Defina isClosed: true para fechar automaticamente o ticket imediatamente após o envio da mensagem. É útil para enviar uma resposta final e arquivar a conversa na mesma requisição.

Janela de Idempotência do externalKey

O externalKey é opcional, mas recomendado. Se o mesmo valor de externalKey for enviado duas vezes dentro de 120 segundos, a segunda chamada é tratada como duplicada. Em vez de enviar novamente, a API retorna:
Isso protege contra envios duplicados acidentais causados por tentativas repetidas ou timeouts de rede.

Uma Única Fonte de Mídia por Requisição

Cada requisição pode incluir no máximo uma das seguintes opções:
  • media: um arquivo enviado como multipart/form-data
  • mediaUrl: uma URL de acesso público apontando para o arquivo
  • base64Data: o conteúdo do arquivo codificado como uma string base64
Não combine duas fontes de mídia na mesma requisição.

Regras do mediaUrl

  • Deve usar o esquema http ou https.
  • Redirecionamentos não são seguidos.
  • Hosts internos, privados ou loopback são bloqueados.

Enviar uma Mensagem de Texto

Responda a uma conversa aberta com uma mensagem de texto simples.
Request
integer
obrigatório
O ID do ticket (conversa) no qual a mensagem será enviada.
string
obrigatório
O conteúdo de texto da mensagem.
string
Chave de idempotência única gerada pelo seu sistema. A janela de deduplicação é de 120 segundos.
boolean
padrão:"false"
Defina como true para reabrir um ticket fechado antes de enviar. Obrigatório se o ticket não estiver atualmente aberto ou pendente.
boolean
padrão:"false"
Defina como true para fechar o ticket imediatamente após o envio da mensagem.

Enviar um Arquivo via URL

Envie um arquivo de uma URL publicamente hospedada para um ticket existente.
Request
integer
obrigatório
O ID do ticket de destino.
string
obrigatório
URL de acesso público do arquivo. Deve usar http ou https. Redirecionamentos e hosts privados não são permitidos.
string
Legenda opcional para acompanhar o arquivo.
string
Chave de idempotência única gerada pelo seu sistema.
boolean
padrão:"false"
Reabre o ticket antes de enviar, caso esteja fechado no momento.
boolean
padrão:"false"
Fecha o ticket após o envio.

Enviar um Arquivo em Base64

Envie um arquivo codificado em base64 diretamente no corpo da requisição, sem necessidade de hospedagem externa. O corpo JSON, já com o base64, pode ter até 50 MB.
Request
integer
obrigatório
O ID do ticket de destino.
string
obrigatório
O conteúdo do arquivo codificado como uma string base64.
string
obrigatório
Tipo MIME do arquivo (obrigatório com base64Data), por exemplo image/png ou application/pdf.
string
Opcional. Nome do arquivo, sem caminho de pastas; por exemplo, captura-de-tela.
string
Legenda opcional para acompanhar o arquivo.
string
Chave de idempotência única gerada pelo seu sistema.
boolean
padrão:"false"
Reabre o ticket antes de enviar, caso esteja fechado no momento.
boolean
padrão:"false"
Fecha o ticket após o envio.

Enviar um Arquivo via Multipart

Envie um arquivo diretamente do seu sistema usando uma requisição multipart/form-data para o mesmo endpoint.

Resposta de Sucesso


Obtendo um ticketId a partir de Webhooks

A forma mais confiável de obter um ticketId é configurar um webhook no seu canal. Quando uma nova mensagem chega, o PanÐá Zap envia (POST) um payload para o seu endpoint que inclui o ID do ticket para todos os tipos de canal, inclusive e-mail. Se preferir não usar webhook, consulte periodicamente /listTickets e /showAllMessages, descritas em Tickets.
A lista do /showAllMessages traz também mensagens de sistema que nunca foram enviadas ao contato: notas internas (mediaType notes ou callNotes) e divisórias de transferência do atendimento (mediaType transfer). Elas não são mensagens do cliente: ao procurar mensagens novas para responder, ignore esses itens pelo mediaType. Veja os detalhes em Obter todas as mensagens de um ticket.
Para ativar os webhooks:
  1. Vá para Administração → Canais.
  2. No cartão do canal, abra o menu de três pontos e clique em Editar.
  3. Abra a seção Webhook do Canal e ative Habilitar Webhook do Canal.
  4. Preencha a URL de destino.
  5. Ative Mensagens recebidas e clique em Salvar alterações.
O formato do payload do webhook é:
Salve o ticket.id de cada webhook recebido para usar com sendMessageByTicket quando precisar responder a essa conversa.