sendMessageByTicket: Responda em Qualquer Tipo de Canal

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 automaticamente e roteia a mensagem para a conversa correta. 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

https://{BaseUrl}/v2/api/external/{ApiID}/

Autenticação

Authorization: Bearer {BearerToken}

Endpoint

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendMessageByTicket

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`

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:

{
  "idempotent": true,
  "skipped": true,
  "ticketId": 1262
}

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

Fornecer mais de uma na mesma requisição retornará um erro de validaçã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

{
  "ticketId": 1262,
  "body": "Hello! How can we help you?",
  "externalKey": "ticket-reply-001",
  "reopen": false,
  "isClosed": false
}

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

{
  "ticketId": 1262,
  "mediaUrl": "https://example.com/invoice.pdf",
  "body": "Your invoice is attached.",
  "externalKey": "ticket-reply-002",
  "reopen": false,
  "isClosed": false
}

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.

Request

{
  "ticketId": 1262,
  "body": "See attached image.",
  "base64Data": "iVBORw0KGgoAAAANSUhEUgAAAAUA...",
  "mimeType": "image/png",
  "fileName": "screenshot",
  "externalKey": "ticket-reply-003",
  "reopen": false,
  "isClosed": false
}

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 — por exemplo, image/png, application/pdf.

string

obrigatório

Nome do arquivo sem extensão — por exemplo, screenshot.

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.

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendMessageByTicket
Content-Type: multipart/form-data

Campo do Formulário	Tipo	Descrição
`media`	arquivo	O arquivo a ser enviado.
`ticketId`	integer	O ID do ticket de destino.
`body`	string	Legenda opcional para acompanhar o arquivo.
`externalKey`	string	Chave de idempotência única.
`reopen`	boolean	Reabre o ticket antes de enviar, caso esteja fechado.
`isClosed`	boolean	Fecha o ticket após o envio.

Resposta de Sucesso

{
  "success": true,
  "data": {
    "message": "Message sent successfully",
    "ticketId": 1262,
    "messageId": "wamid.xxxx"
  }
}

Campo	Tipo	Descrição
`success`	boolean	`true` quando a mensagem foi aceita para entrega.
`data.message`	string	Confirmação legível por humanos.
`data.ticketId`	integer	O ID da conversa na qual a mensagem foi enviada.
`data.messageId`	string	Identificador único da mensagem no canal. Use-o com `GET /getMessageByMessageId?messageId=wamid.xxxx` para consultar a mensagem posteriormente.

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 — incluindo e-mail. Para ativar os webhooks:

Vá para Administração → Canais.
Selecione o canal e clique em Editar.
Ative a chave Webhook.
Defina sua URL do Webhook.
Ative Mensagens Recebidas.

O formato do payload do webhook é:

{
  "method": "message",
  "msg": { ... },
  "ticket": {
    "id": 1262,
    ...
  }
}

Salve o ticket.id de cada webhook recebido para usar com sendMessageByTicket quando precisar responder a essa conversa.

Primeiros Passos

Mensagens

Tickets e Contatos

Campanhas e CRM

Webhooks e Eventos

sendMessageByTicket: Responda em Qualquer Tipo de Canal

Visão Geral

Conceitos-Chave

`reopen`

`isClosed`

Janela de Idempotência do `externalKey`

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

Regras do `mediaUrl`

Enviar uma Mensagem de Texto

Enviar um Arquivo via URL

Enviar um Arquivo em Base64

Enviar um Arquivo via Multipart

Resposta de Sucesso

Obtendo um `ticketId` a partir de Webhooks

​Visão Geral

​Conceitos-Chave

​reopen

​isClosed

​Janela de Idempotência do externalKey

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

​Regras do mediaUrl

​Enviar uma Mensagem de Texto

​Enviar um Arquivo via URL

​Enviar um Arquivo em Base64

​Enviar um Arquivo via Multipart

​Resposta de Sucesso

​Obtendo um ticketId a partir de Webhooks

Visão Geral

Conceitos-Chave

`reopen`

`isClosed`

Janela de Idempotência do `externalKey`

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

Regras do `mediaUrl`

Enviar uma Mensagem de Texto

Enviar um Arquivo via URL

Enviar um Arquivo em Base64

Enviar um Arquivo via Multipart

Resposta de Sucesso

Obtendo um `ticketId` a partir de Webhooks