Enviar elementos nativos
Quando a sua ferramenta devolve um código Pix como texto, a IA precisa copiá-lo na resposta, e modelos erram códigos longos. Com a chave atalia.send no resultado, a própria Atalia envia o elemento nativo do canal: o card de pagamento do WhatsApp, botões de resposta, um carrossel de produtos, um PDF. A IA não reproduz nada, e o cliente recebe a mensagem certa.
Onde o canal não tem o elemento, a Atalia adapta ou manda como texto, sozinha. Veja Suporte por canal.
Estrutura
Acrescente a chave atalia ao lado do que a ferramenta já devolve:
{
"data": { "transaction_id": "PD6CB214D" },
"atalia": {
"send": [
{ "type": "text", "text": "Prontinho, gerei a sua cobrança." },
{ "type": "order_details", "reference_id": "PD6CB214D", "...": "..." }
],
"final": true
}
}
send: a lista do que enviar, na ordem. Um objeto só também vale. No máximo 10 por resultado.final: veja abaixo.- O resto do resultado (
data,success...) continua chegando para a IA como antes.
A Atalia procura a chave em atalia, data.atalia, [0].atalia ou [0].data.atalia, com o resultado em objeto ou em texto JSON. Se a sua ferramenta já devolve [{ "success": true, "data": {...} }], basta acrescentar atalia ao lado.
final
Use "final": true quando o que foi enviado já responde o cliente. Sem isso, a IA lê o resultado e escreve mais uma mensagem por cima ("Enviei o Pix acima!"). Deixe sem final quando a IA ainda precisa complementar, por exemplo para explicar as opções que acabou de mandar.
Tipos
Pagamento: order_details
O card de pagamento do WhatsApp, com o botão Copiar código Pix (ou um botão para o link de pagamento).
{
"type": "order_details",
"reference_id": "PD6CB214D",
"body_text": "Pague com Pix para confirmar seu pedido:",
"total_amount_cents": 5270,
"items": [{ "name": "Consulta", "quantity": 1, "unit_price_cents": 5270 }],
"payment": {
"type": "pix_dynamic_code",
"code": "00020101021226800014br.gov.bcb.pix2558...",
"merchant_name": "Clínica Bem-Estar",
"key": "11222333000181",
"key_type": "CNPJ"
},
"fallback_text": "Pague com Pix. Código copia-e-cola:\n\n{code}"
}
| Campo | Obrigatório | O que é |
|---|---|---|
reference_id | Sim | Identificador único da cobrança. É por ele que você confirma o pagamento depois: o WhatsApp não concilia por você. |
total_amount_cents | Sim | Total em centavos (5270 = R$ 52,70). |
payment.type | Sim | pix_dynamic_code (Pix) ou payment_link (link de checkout). |
payment.code, merchant_name, key, key_type | Sim, no Pix | Código copia-e-cola, nome do recebedor e a chave Pix. key_type: CPF, CNPJ, EMAIL, PHONE ou EVP. |
body_text | Não | Texto acima do card. |
items | Não | Itens do pedido. Sem itens, vai um item único com o total. |
discount_cents, delivery_fee_cents, increase_cents | Não | Desconto, frete e acréscimo. A Atalia fecha a conta que o WhatsApp exige. |
currency | Não | Padrão BRL. |
fallback_text | Não | Texto usado se o card não puder ser enviado. {code} e {url} viram o código Pix e o link. |
Para link de pagamento, troque o payment por:
"payment": { "type": "payment_link", "uri": "https://checkout.exemplo.com/abc123" }
O card só sai em contas com Pagamentos no WhatsApp aprovado pela Meta. Sem isso a Meta recusa, e a Atalia reenvia o fallback_text como texto na hora: o cliente sempre recebe algo que dá para pagar. No webchat o card aparece no próprio widget, sem aprovação nenhuma.
Atualizar o pedido: order_status
Depois que o pagamento cair, avise o WhatsApp. É obrigatório depois de um order_details pago: sem isso o card fica em "aguardando pagamento" no celular do cliente. Use o mesmo reference_id.
{
"type": "order_status",
"reference_id": "PD6CB214D",
"status": "processing",
"description": "Pagamento confirmado! Seu pedido está em preparação.",
"payment": { "status": "captured", "timestamp": 1772445231 }
}
status: pending, processing, shipped, completed ou canceled (assim, com um L só, como a Meta escreve).
Botões: buttons
Até 3 botões de resposta, com título de até 20 caracteres. O toque volta para o agente como resposta do cliente (com o id), e também pode disparar um gatilho de fluxo.
{
"type": "buttons",
"body": "Como prefere receber seu pedido?",
"footer": "Escolha uma opção",
"buttons": [
{ "id": "entrega", "title": "Entrega" },
{ "id": "retirada", "title": "Retirar na loja" }
]
}
Lista: list
Um menu com até 10 opções no total, em até 10 seções. Bom para horários, unidades, serviços.
{
"type": "list",
"body": "Escolha o horário do seu atendimento:",
"button": "Ver horários",
"sections": [
{ "title": "Manhã", "rows": [
{ "id": "h_09", "title": "09:00", "description": "Dra. Ana" },
{ "id": "h_10", "title": "10:00", "description": "Dr. Paulo" }
]}
]
}
Carrossel: carousel
De 2 a 10 cards, cada um com imagem (ou vídeo) e um botão de link ou de resposta.
{
"type": "carousel",
"body_text": "Veja o que separamos para você:",
"cards": [
{ "image_url": "https://cdn.exemplo.com/kit-1.jpg", "body_text": "Kit Essencial, R$ 89,90",
"button_text": "Ver produto", "button_url": "https://loja.exemplo.com/kit-essencial" },
{ "image_url": "https://cdn.exemplo.com/kit-2.jpg", "body_text": "Kit Premium, R$ 149,90",
"button_type": "quick_reply", "button_id": "kit_premium", "button_text": "Quero este" }
]
}
Botão de link: cta_url
Um botão que abre um endereço. Melhor que colar o link no texto.
{ "type": "cta_url", "body": "Sua segunda via está pronta.", "display_text": "Baixar boleto", "url": "https://financeiro.exemplo.com/boleto/123" }
Mídia: image, video, audio, document
{ "type": "image", "url": "https://cdn.exemplo.com/tabela.jpg", "caption": "Nossa tabela de preços" }
{ "type": "document", "url": "https://cdn.exemplo.com/boleto-123.pdf", "filename": "boleto-123.pdf", "caption": "Segunda via" }
{ "type": "video", "url": "https://cdn.exemplo.com/como-usar.mp4", "caption": "Como usar" }
{ "type": "audio", "url": "https://cdn.exemplo.com/recado.ogg" }
A Atalia baixa o arquivo e envia pelo canal. Regras da url:
- só
httpse endereço público (endereço interno ou de rede privada é recusado, também depois de redirecionamento); - o tipo do arquivo tem que bater com o declarado (documento aceita qualquer tipo);
- limites da Meta: imagem 5 MB, vídeo e áudio 16 MB, documento 100 MB;
- sem usuário e senha na URL; o download tem 15 segundos.
Se o download falhar, a legenda vai como texto e o erro volta para a IA.
Localização e contato: location, contacts
{ "type": "location", "latitude": -23.5613, "longitude": -46.6565, "name": "Loja Paulista", "address": "Av. Paulista, 1000, São Paulo/SP" }
{ "type": "contacts", "contacts": [
{ "name": { "formatted_name": "Financeiro Loja Exemplo", "first_name": "Financeiro" },
"phones": [{ "phone": "+5511999999999", "type": "WORK" }] }
]}
Texto: text
{ "type": "text", "text": "Recebemos seu pedido!" }
Útil para pôr uma frase antes ou entre elementos nativos.
Exemplos por situação
Clínica: escolher e confirmar o horário
A ferramenta horarios_livres devolve os horários e manda a lista. Sem final, porque a IA pode completar ("Se nenhum servir, posso ver outro dia").
{
"data": { "dia": "2026-11-03", "horarios": ["09:00", "10:00", "14:30"] },
"atalia": {
"send": [{
"type": "list",
"body": "Estes são os horários livres na terça, 3/11:",
"button": "Ver horários",
"sections": [{ "title": "Terça, 3/11", "rows": [
{ "id": "2026-11-03T09:00", "title": "09:00" },
{ "id": "2026-11-03T10:00", "title": "10:00" },
{ "id": "2026-11-03T14:30", "title": "14:30" }
]}]
}]
}
}
Depois que o cliente escolhe, a ferramenta agendar confirma, manda o endereço e encerra a vez da IA:
{
"success": true,
"data": { "agendamento": "AG-5521" },
"atalia": {
"send": [
{ "type": "text", "text": "Consulta marcada para terça, 3/11, às 09:00. Te esperamos!" },
{ "type": "location", "latitude": -23.5613, "longitude": -46.6565, "name": "Clínica Bem-Estar", "address": "Av. Paulista, 1000, São Paulo/SP" }
],
"final": true
}
}
Loja: mostrar produtos, cobrar e confirmar
buscar_produtos manda o carrossel; gerar_cobranca manda o Pix e marca a conversa:
{
"success": true,
"data": { "pedido": "PED-1042", "total": "R$ 52,70" },
"atalia": {
"send": [{
"type": "order_details",
"reference_id": "PED-1042",
"body_text": "Pague com Pix para confirmar o pedido PED-1042:",
"total_amount_cents": 5270,
"items": [{ "name": "Kit Essencial", "quantity": 1, "unit_price_cents": 4500 }],
"delivery_fee_cents": 770,
"payment": { "type": "pix_dynamic_code", "code": "000201...", "merchant_name": "Loja Exemplo", "key": "11222333000181", "key_type": "CNPJ" },
"fallback_text": "Pague com Pix (copia e cola):\n\n{code}"
}],
"tags": { "add": ["aguardando-pagamento"] },
"final": true
}
}
Quando o cliente avisa que pagou, verificar_pagamento confere no gateway e atualiza o card, a tag e o status:
{
"success": true,
"data": { "pedido": "PED-1042", "pago": true },
"atalia": {
"send": [{ "type": "order_status", "reference_id": "PED-1042", "status": "processing", "description": "Pagamento confirmado! Seu pedido está em preparação." }],
"tags": { "add": ["venda-ganha"], "remove": ["aguardando-pagamento"] },
"status": "closed",
"final": true
}
}
Financeiro: segunda via
{
"success": true,
"data": { "vencimento": "10/11/2026", "valor": "R$ 189,90" },
"atalia": {
"send": [
{ "type": "document", "url": "https://financeiro.exemplo.com/boletos/123.pdf", "filename": "boleto-novembro.pdf", "caption": "Segunda via, vencimento 10/11" },
{ "type": "cta_url", "body": "Se preferir, pague pelo navegador:", "display_text": "Pagar agora", "url": "https://financeiro.exemplo.com/pagar/123" }
],
"final": true
}
}
Atendimento: passar o contato de um setor
{
"data": { "setor": "financeiro" },
"atalia": {
"send": [
{ "type": "text", "text": "Esse assunto é com o nosso financeiro. Segue o contato:" },
{ "type": "contacts", "contacts": [{ "name": { "formatted_name": "Financeiro Loja Exemplo", "first_name": "Financeiro" }, "phones": [{ "phone": "+5511999999999", "type": "WORK" }] }] }
],
"final": true
}
}
Suporte por canal
Você não precisa saber o canal da conversa. O que o canal não tem, a Atalia adapta ou manda como texto: o Pix vira o código copia-e-cola, botões e listas viram opções numeradas, a localização vira o link do mapa. Para um texto melhor que o padrão, mande fallback_text.
| Tipo | WhatsApp (QR Code) | Webchat | Instagram e Messenger | ||
|---|---|---|---|---|---|
text, image, video, audio, document | Nativo | Nativo | Nativo | Nativo | Nativo |
buttons | Nativo | Nativo | Nativo | Respostas rápidas | Texto |
list | Nativo | Nativo | Nativo | Respostas rápidas (até 13) | Texto |
cta_url | Nativo | Nativo | Nativo | Botão de link | Texto |
carousel | Nativo | Nativo | Nativo | Texto | Texto |
order_details, order_status | Nativo | Texto | Nativo | Texto | Texto |
location, contacts | Nativo | Nativo | Nativo (card) | Texto | Texto |
Quando um menu vira texto, o cliente responde "1", "2"... e a Atalia entende como o toque na opção, com o id original.
Erros
A Atalia confere cada item antes de enviar, com os limites da Meta. Se algo estiver errado, aquele item não é enviado e o erro volta junto do resultado, para a IA corrigir ou explicar:
[atalia] Falha ao enviar elemento nativo: buttons: o WhatsApp permite no máximo 3 botões de resposta
Os outros itens válidos do mesmo resultado são enviados normalmente. Um item com erro nunca interrompe a conversa nem o fluxo.
| Erro comum | Como resolver |
|---|---|
| Mais de 3 botões ou título com mais de 20 caracteres | Use list para mais opções; encurte o título |
| Lista com mais de 10 linhas | Divida em duas mensagens ou filtre as opções |
| Carrossel com 1 card ou mais de 10 | Para 1 item, use image + buttons |
Mídia em http, endereço interno ou acima do limite | Hospede em https público e respeite o tamanho |
order_details sem key/key_type no Pix | Informe a chave Pix do recebedor |
Veja também
- Ferramentas próprias (MCP): conectar o servidor e o formato do resultado.
- Mudar a conversa e registrar conversões:
status,tagseevent.