WhatsApp Template API

API para desenvolvedores

Envie templates aprovados do WhatsApp a partir dos seus próprios sistemas com uma única chamada de API; a conversa continua depois no MonoChat.

• WhatsApp
• API REST
• Somente API

Instalar pela MonoStoreVer em monochat.ai

Visão geral

A WhatsApp Template API permite que o seu CRM, ERP, loja virtual ou qualquer backend envie uma mensagem de template do WhatsApp aprovada a um cliente por meio do MonoChat. Uma única requisição informa o número de WhatsApp de origem, o telefone do cliente, o template e suas variáveis.

Quando o cliente responde, a conversa chega à sua caixa de entrada do MonoChat como qualquer outra. O app não tem telas próprias: tudo acontece por três endpoints de API.

Destaques

• Uma chamada de API. Envie um template por nome e idioma, com as variáveis de cabeçalho, corpo, botão e carrossel preenchidas com os seus dados.
• Direto para o chat. Cada envio retorna o id da conversa e um link direto para ela no MonoChat.
• Clientes novos são bem-vindos. Se o número de telefone ainda não for um cliente, o cliente é criado com o nome que você enviar.

Instalação e configuração

1. Conecte o seu número do WhatsApp Business ao MonoChat e verifique se ele está verificado e tem templates aprovados pela Meta.
2. Instale a WhatsApp Template API em Configurações › MonoStore › Aplicativos, ou abra o link de instalação app.monochat.ai/apps/K6u29LpbwCHBozZ8o. Se você ainda não tem uma conta MonoChat, o link permite que você se cadastre primeiro e instala o app para você.
3. Crie um token de API em Perfil › Tokens de API. O token é exibido apenas uma vez, então copie-o imediatamente.
4. Chame template/list.js para ver os seus templates aprovados e as variáveis deles.
5. Chame template/send.js com o número do cliente e os valores das variáveis para enviar o seu primeiro template.

observação

• Cada mensagem é cobrada como qualquer mensagem de template enviada pelo MonoChat.
• As URLs de mídia devem continuar acessíveis até que o WhatsApp baixe o arquivo.
• Envie para clientes que concordaram em receber suas mensagens: o WhatsApp pode limitar números cujas mensagens são bloqueadas ou denunciadas.

Recursos

Listar templates

Os templates aprovados de um número de WhatsApp, com idioma, categoria, status e variáveis, para que o seu sistema saiba o que pode enviar.

Enviar um template

Por nome e idioma do template, com variáveis de cabeçalho, corpo, botão e carrossel. Um valor ausente interrompe o envio, então nada preenchido pela metade chega ao cliente.

Atribuir a um atendente

Informe o e-mail de um atendente e a conversa é aberta no nome dele.

Cabeçalhos de mídia

Obtenha credenciais de upload de curta duração, coloque uma imagem, um vídeo ou um documento no armazenamento do MonoChat e use a URL dele como cabeçalho do template.

Link da conversa

Cada envio retorna o id da sessão, o id da mensagem e um link que abre a conversa no MonoChat.

Erros claros

Uma chamada com falha informa o que deu errado, por exemplo “Channel not found” ou “Variable missing”.

Antes de começar

• O seu número do WhatsApp Business está conectado ao MonoChat e verificado. Veja Canais.
• Os templates que você quer enviar estão aprovados pela Meta. Os templates são a forma de escrever primeiro ou de alcançar um cliente fora da janela de 24 horas. Veja Mensagens de modelo.
• Você tem um token de API em Perfil › Tokens de API. Veja Tokens de API.
• Você sabe qual é o seu tenant slug: a parte depois de /tenants/ no seu endereço do MonoChat. Em https://app.monochat.ai/tenants/mybusiness o slug é mybusiness.

Referência da API

O app não tem telas próprias. Tudo acontece por três endpoints, cada um um POST com um corpo JSON:

POST https://app.monochat.ai/api/<slug>/custom-functions/template-app/api/<endpoint>
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

Endpoint	O que faz
template/list.js	Lista os templates de um dos seus números de WhatsApp, com as variáveis deles.
template/send.js	Envia um template a um cliente e retorna um link para a conversa.
upload/get-token.js	Fornece credenciais de upload de curta duração para uma imagem, um vídeo ou um documento de cabeçalho.

Os números de telefone são sempre escritos com o código do país e sem +, por exemplo 905334445566. Uma chamada bem-sucedida responde 200 com os dados do endpoint em result.

1. Listar templates

POST /api/<slug>/custom-functions/template-app/api/template/list.js

Lista todos os templates do número de WhatsApp Business informado: nome, código de idioma, categoria, componentes (cabeçalho, corpo, rodapé, botões), tipos de variável e status de aprovação.

Campo	Obrigatório	Descrição
phoneNumber	sim	O seu número do WhatsApp Business no MonoChat, com código do país, sem +.
options	não	Paginação e filtros, por exemplo { "pagination": { "currentPage": 1, "pageItems": 50 } }.

POST /api/<slug>/custom-functions/template-app/api/template/list.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566"
}

Resposta (resumida):

{
  "result": {
    "templateMessages": [
      {
        "name": "new_product_announcement",
        "languageCode": "tr-TR",
        "category": "MARKETING",
        "components": [
          {
            "type": "HEADER",
            "format": "IMAGE",
            "variables": [
              { "type": "IMAGE", "value": null, "exampleValue": "https://.../sample-image.png" }
            ]
          },
          {
            "type": "BODY",
            "text": "Merhaba {{1}}, yeni ürünümüz {{2}} çıktı!",
            "sampleText": "Merhaba [Ayşe], yeni ürünümüz [XYZ Telefon] çıktı.",
            "variables": [
              { "type": "TEXT", "value": null, "exampleValue": "[Ayşe]" },
              { "type": "TEXT", "value": null, "exampleValue": "[XYZ Telefon]" }
            ]
          },
          {
            "type": "FOOTER",
            "text": "Teşekkürler",
            "sampleText": "Teşekkürler"
          }
        ],
        "status": "APPROVED"
      }
    ],
    "options": {
      "pagination": { "totalCount": 12, "currentPage": 1, "pageItems": 12, "totalPages": 1 }
    }
  }
}

Como ler a resposta:

• name: o nome de sistema com o qual você envia o template.
• languageCode: o idioma em que ele será enviado.
• category: a categoria do WhatsApp (MARKETING, UTILITY, AUTHENTICATION).
• components: as partes de que o template é composto.

Componente	Conteúdo	Descrição
HEADER	IMAGE, VIDEO, DOCUMENT ou texto	Para mídia, o format é informado; as variáveis aparecem em variables.
BODY	Texto com variáveis	O corpo da mensagem, com marcadores como {{1}}, {{2}}.
FOOTER	Texto	Normalmente não tem variáveis.
BUTTONS	URL, resposta rápida…	Os textos dos botões e as variáveis deles, se houver.

O template de exemplo acima precisa de uma imagem para o cabeçalho e de dois textos para o corpo (nome do cliente e nome do produto). O rodapé é fixo ("Teşekkürler") e não há botões.

2. Enviar um template

POST /api/<slug>/custom-functions/template-app/api/template/send.js

Envia um template aprovado a um cliente. Se o número de telefone ainda não for um cliente, o cliente é criado; a conversa é aberta (ou reaproveitada) e o template é enviado nela.

Campo	Obrigatório	Descrição
phoneNumber	sim	O número do WhatsApp Business de origem. Ele deve estar conectado ao MonoChat e verificado.
templateMessageName	sim	O name do template, exatamente como a listagem o retorna.
languageCode	sim	O idioma do template, como a listagem o retorna (por exemplo tr-TR).
customerPhoneNumber	sim	O número de WhatsApp do cliente.
variables	quando o template tiver alguma	Os valores das variáveis do template (veja abaixo).
customerFirstName, customerLastName	não	Usados quando o cliente é novo no MonoChat.
agentEmailAddress	não	Atribui a conversa ao atendente com este e-mail.

Variáveis. Cada item do array variables tem um type e uma lista de parameters, informados na ordem dos marcadores do template:

type	parameters
HEADER	A variável de texto do cabeçalho, ou a URL pública da imagem, do vídeo ou do documento do cabeçalho.
BODY	Os {{1}}, {{2}}, … do corpo, em ordem.
BUTTONS	Um valor para cada botão que tem variável (por exemplo, a parte dinâmica de um botão de URL ou um código de cupom), na ordem dos botões.
CAROUSEL	Em vez de parameters, um array cards com uma entrada por cartão do carrossel, cada uma com seus próprios components.

{ "type": "CAROUSEL", "cards": [ { "components": [ { "type": "HEADER", "parameters": ["https://…/1.jpg"] }, { "type": "BODY", "parameters": ["…"] } ] } ] }

Um valor ausente interrompe o envio com Variable missing, então nada preenchido pela metade chega ao cliente. O FOOTER raramente tem variáveis.

POST /api/<slug>/custom-functions/template-app/api/template/send.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566",
  "templateMessageName": "new_product_announcement",
  "languageCode": "tr-TR",
  "customerPhoneNumber": "905306667788",
  "customerFirstName": "Ayşe",
  "agentEmailAddress": "sarah@yourcompany.com",
  "variables": [
    { "type": "HEADER", "parameters": ["https://…/product.jpg"] },
    { "type": "BODY", "parameters": ["Ayşe", "XYZ Phone"] }
  ]
}

Resposta:

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "…",
    "messageId": "…"
  }
}

• url: abre a conversa no MonoChat, para as pessoas que estão conectadas e têm permissão para vê-la.
• sessionId: o id da conversa.
• messageId: o id da mensagem no MonoChat. O status de entrega e de leitura dela aparece no chat como o de qualquer outra mensagem.

Mídia em templates. O WhatsApp baixa a mídia do cabeçalho a partir da URL que você informar, então a URL deve ser válida e publicamente acessível. Links que exigem login não funcionam. Se você enviou o arquivo com upload/get-token.js, use a URL do arquivo montada a partir dessa resposta.

3. Enviar mídia para um cabeçalho

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js

Quando o cabeçalho de um template é uma imagem, um vídeo ou um documento, o arquivo precisa de um endereço público de onde o WhatsApp possa baixá-lo. Este endpoint dá a você uma permissão de curta duração para colocar o arquivo no armazenamento do MonoChat.

Campo	Obrigatório	Descrição
fileName	sim	O nome do arquivo com a extensão, por exemplo product.jpg ou promo.pdf.

Os arquivos são sempre armazenados na pasta chat-assets do seu workspace; exemplos mais antigos que enviam um campo key continuam funcionando, o valor não é necessário.

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "fileName": "product.jpg"
}

A resposta informa onde colocar o arquivo e fornece as credenciais para isso:

Campo	Descrição
bucket, region, path	Onde o arquivo vai.
temporaryCredentials	Credenciais somente de upload para aquele caminho, válidas por 15 minutos.
baseUrl	O endereço público do armazenamento. A URL do arquivo é baseUrl + / + path.

Envie o arquivo imediatamente com qualquer cliente S3 usando essas credenciais e depois passe a URL dele como o parâmetro HEADER ao enviar o template. Arquivos muito grandes ou formatos que o WhatsApp não aceita (ele aceita os formatos comuns de imagem, vídeo e PDF) falham.

Exemplo: um template com cabeçalho de imagem

Digamos que você tenha um template aprovado new_product_announcement com um cabeçalho de imagem e duas variáveis no corpo (nome do cliente e nome do produto) e queira enviá-lo a um cliente.

1. Liste os templates. Chame template/list.js com o seu número de WhatsApp e encontre new_product_announcement. Os componentes dele mostram uma variável IMAGE no cabeçalho e duas variáveis TEXT no corpo.
2. Envie a imagem. Chame upload/get-token.js com { "fileName": "urun.jpg" }, envie o arquivo com as credenciais retornadas e monte a URL dele a partir de baseUrl e path.
3. Envie o template. Chame template/send.js com a URL do arquivo como parâmetro HEADER e ["Ayşe", "XYZ Telefon"] como parâmetros BODY ({{1}} → Ayşe, {{2}} → XYZ Telefon). Se o template tivesse variáveis de botão, você adicionaria um item BUTTONS da mesma forma.
4. Abra o chat. O url da resposta abre a conversa; quando o cliente responde, ela continua na sua caixa de entrada do MonoChat.

Erros

Uma chamada com falha responde com um status de erro e uma mensagem que informa o que deu errado. Registre essas mensagens no seu sistema e mostre uma mensagem compreensível aos seus usuários quando necessário.

Mensagem	Causa
phoneNumber field is required	template/list.js foi chamado sem phoneNumber.
phoneNumber, templateMessageName, customerPhoneNumber fields are required	Falta um campo obrigatório de template/send.js.
Channel not found	O phoneNumber não é um número de WhatsApp do seu workspace.
Channel is not verified	O número de WhatsApp está conectado, mas não verificado.
Template message not found	Não há nenhum template aprovado com esse nome e idioma no número. Confira a grafia e o languageCode.
Template message is not approved	O template existe, mas não está aprovado pela Meta.
Variable missing: …	variables não corresponde ao template, por exemplo o template precisa de dois valores no corpo e você enviou um.
Agent user not found	Não há nenhum atendente com o e-mail de agentEmailAddress.
Customer Channel not found	A identidade de WhatsApp do cliente não pôde ser criada ou encontrada.

Códigos de status HTTP que você pode ver:

• 401 Unauthorized: o cabeçalho Authorization: Bearer <API_TOKEN> está ausente, ou o token está errado ou expirou. Use um token válido da sua conta.
• 403 Forbidden: o token não tem acesso a este workspace ou app, por exemplo por um tenant slug errado.
• 404 Not Found: o endereço do endpoint está errado. Confira o caminho completo /api/<slug>/custom-functions/template-app/api/....
• 500 Internal Server Error: um problema inesperado no MonoChat ou no provedor do WhatsApp, ou uma recusa do lado do WhatsApp (o número não está no WhatsApp, o cliente bloqueou você, limites de qualidade ou de taxa). Tente novamente mais tarde e entre em contato com o suporte do MonoChat se o problema persistir.

Capturas de tela

Envio de um template aprovado do WhatsApp a partir de um CRM, ERP ou sistema de e-commerce com uma única chamada de API por meio do MonoChatA lista de templates aprovados do WhatsApp com as variáveis delesEnviar um template para um número novo cria o cliente automaticamenteUm template enviado em vários idiomasTemplates com cabeçalhos de imagem, vídeo, documento e PDF

Perguntas frequentes

A WhatsApp Template API tem interface de usuário?

Não. É um app somente de API com três endpoints: listar templates, enviar um template e obter credenciais de upload para cabeçalhos de mídia.

O que preciso antes de poder usá-la?

Um número do WhatsApp Business conectado ao MonoChat e verificado, templates aprovados pela Meta e um token de API em Perfil › Tokens de API.

O que acontece quando o cliente responde?

A conversa chega à sua caixa de entrada do MonoChat como qualquer outra. Cada envio também retorna um link direto para a conversa, e você pode atribuí-la a um atendente por e-mail.

Posso enviar para um número que ainda não é cliente?

Sim. Se o número de telefone ainda não for um cliente, o cliente é criado com o nome que você enviar.

Quanto custam as mensagens de template?

Cada mensagem é cobrada como qualquer mensagem de template enviada pelo MonoChat. A Meta define o preço dos templates por categoria e pelo país do destinatário; use a calculadora de custo de disparos em massa do WhatsApp para estimar um envio.

Relacionados

• Session Link
• Bulk Template Message API
• Mensagens de modelo
• Aplicativos da MonoStore