> For the complete documentation index, see [llms.txt](https://docs.otima.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.otima.io/whatsapp/recursos-de-api/templates-hsm.md). # Templates (HSM) Envie templates fora da janela de atendimento. Todas as requisições devem ser feitas utilizando autenticação Bearer Token. ### Envios de templates URL Base de envio de template: ```http POST https://sync-core-api.otima.io/whatsapp/provider/{{NUMERO_AQUI}}/send-message ``` *** #### Categorias templates * `marketing` * `utility` * `authentication` #### Tipos * `marketing_lite` -- apenas templates marketing * `cloud_api` *** #### Recursos Disponíveis * Variáveis dinâmicas do template * Header com imagem, vídeo ou documento * Botões URL * Botões de resposta rápida * Parâmetros personalizados {% hint style="danger" %} #### Importante * As imagens utilizadas no envio de templates não devem exceder **5 MB**. Caso o arquivo ultrapasse esse limite, a **Meta** retornará um status **`failed`** no evento correspondente do **Webhook**, indicando que a mensagem não pôde ser processada devido ao tamanho da imagem. 
{
    "code": 131053,
    "title": "Media upload error",
    "message": "Media upload error",
    "retryable": false,
    "classification": "UserError",
    "details": {
      "file_size_bytes": 5780195,
      "max_size_bytes": 5242880,
      "reason": "Image exceeds maximum allowed size"
    }
}
{% endhint %} #### Estrutura para o Envio do template (payload) ```json { "messaging_product": "whatsapp", "to": "5511999999999", "type": "template", "template": { "name": "confirmacao_pedido", "language": { "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "Marcio" }, { "type": "text", "text": "12345" } ] } ] } } ``` *** ### Criar Template Cria um novo template de mensagem diretamente na Meta/WhatsApp Business API. Após a criação, o template entra automaticamente em processo de análise da Meta e poderá assumir status como: * `PENDING` * `APPROVED` * `REJECTED` O template criado ficará disponível para envio somente após aprovação da Meta. #### Endpoint ```http POST https://sync-core-api.otima.io/whatsapp/provider/workspace-templates ``` #### Estrutura de criação do template O payload segue exatamente o padrão esperado pela Meta. #### Waba ids (multi-criação) O campo `waba_ids` permite criar o mesmo template simultaneamente em **uma ou mais Wabas dentro do mesmo Business Manager**. Isso facilita a padronização de templates entre diferentes números e contas, evitando criação duplicada manual. #### Comportamento * Se um único `waba_id` for enviado → o template será criado apenas naquela WABA * Se múltiplos `waba_ids` forem enviados → o template será replicado em todas as WABAs informadas * O resultado retorna um **UUID único do template no workspace**, independente da quantidade de WABAs utilizadas #### Exemplo payload — Criando Template simples ```json { "waba_ids": [876471289312412, 921244215126634], "name": "confirmacao_pedido", "category": "utility", "type": "cloud_api", "language": "pt_BR", "components": [ { "type": "BODY", "text": "Olá {{1}}. Seu pedido {{2}} foi confirmado." } ] } ``` #### Exemplo payload completo — Criando Template com Header, Footer e Botões ```json { "waba_ids": [876471289312412], "name": "pedido_confirmado", "category": "utility", "type": "cloud_api", "language": "pt_BR", "components": [ { "type": "HEADER", "format": "IMAGE" }, { "type": "BODY", "text": "Olá {{1}}. Seu pedido {{2}} foi aprovado." }, { "type": "FOOTER", "text": "Equipe Comercial" }, { "type": "BUTTONS", "buttons": [ { "type": "URL", "text": "Acompanhar Pedido", "url": "https://site.com/pedido/{{1}}" }, { "type": "QUICK_REPLY", "text": "Falar com suporte" } ] } ] } ``` #### Criar template com mídia no header Para enviar mídia no header, use `multipart/form-data` e o campo `header_file`. Substitua os valores entre `{{ }}` antes de enviar a requisição. Não use dados reais nos exemplos. **Header com imagem** ```bash curl --location 'https://sync-core-api.otima.io/whatsapp/provider/workspace-templates' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {{token}}' \ --header 'x-workspace-uuid: {{workspace_uuid}}' \ --form 'waba_ids="{{waba_id}}"' \ --form 'name="{{template_name}}"' \ --form 'language="pt_BR"' \ --form 'category="UTILITY"' \ --form 'header_file=@"./header-image.jpg"' \ --form 'components=[{"type":"HEADER","format":"IMAGE","example":{"header_handle":["UPLOAD_PENDING"]}},{"type":"BODY","text":"Olá {{1}}. Confira o conteúdo enviado."}]' ``` **Header com documento** ```bash curl --location 'https://sync-core-api.otima.io/whatsapp/provider/workspace-templates' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {{token}}' \ --header 'x-workspace-uuid: {{workspace_uuid}}' \ --form 'waba_ids="{{waba_id}}"' \ --form 'name="{{template_name}}"' \ --form 'language="pt_BR"' \ --form 'category="UTILITY"' \ --form 'header_file=@"./header-document.pdf"' \ --form 'components=[{"type":"HEADER","format":"DOCUMENT","example":{"header_handle":["UPLOAD_PENDING"]}},{"type":"BODY","text":"Olá {{1}}. Seu documento está disponível."}]' ``` **Header com vídeo** ```bash curl --location 'https://sync-core-api.otima.io/whatsapp/provider/workspace-templates' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {{token}}' \ --header 'x-workspace-uuid: {{workspace_uuid}}' \ --form 'waba_ids="{{waba_id}}"' \ --form 'name="{{template_name}}"' \ --form 'language="pt_BR"' \ --form 'category="UTILITY"' \ --form 'header_file=@"./header-video.mp4"' \ --form 'components=[{"type":"HEADER","format":"VIDEO","example":{"header_handle":["UPLOAD_PENDING"]}},{"type":"BODY","text":"Olá {{1}}. Assista ao vídeo enviado."}]' ``` {% hint style="info" %} O valor de `format` deve corresponder ao arquivo enviado: `IMAGE`, `DOCUMENT` ou `VIDEO`. {% endhint %} *** ### Editar Template Atualiza os campos permitidos de um template existente. * **Método**: `PUT` * **Endpoint**: ```http https://sync-core-api.otima.io/whatsapp/provider/workspace-templates/{uuid} ``` Envie `Authorization: Bearer {token}` e `x-workspace-uuid: {workspace_uuid}` em todas as requisições. Use o `{uuid}` interno retornado na criação ou na listagem de templates. #### Campos aceitos | Campo | Tipo | Obrigatório | Descrição | | ------------------ | --------------------- | ----------- | ------------------------------------------------------------------------------------- | | `category` | string | Não | Categoria do template. | | `sub_category` | string | Não | Subcategoria do template. | | `components` | array JSON | Não | Componentes atualizados do template. Em `multipart/form-data`, envie uma string JSON. | | `parameter_format` | string | Não | Formato dos parâmetros. Exemplo: `NAMED`. | | `workspace_uuid` | string | Não | Workspace de destino em contexto administrativo. | | `is_administrator` | boolean | Não | Indica contexto administrativo. | | `pix_data` | objeto ou string JSON | Não | Dados PIX do template. | | `order_data` | objeto ou string JSON | Não | Dados de pedido do template. | | `header_file` | arquivo | Não | Arquivo de mídia do header. | | `pix_file` | arquivo | Não | Arquivo associado aos dados PIX. | | `order_file` | arquivo | Não | Arquivo associado aos dados de pedido. | | `carousel_files[]` | arquivos | Não | Arquivos opcionais dos cards de carrossel. | {% hint style="warning" %} `name`, `language`, `waba_ids`/`waba_id` e `business_id` são imutáveis após a criação. Não envie esses campos no `PUT`. {% endhint %} Use `application/json` quando não houver mídia. Use `multipart/form-data` ao enviar qualquer arquivo. #### Exemplo sem mídia ```bash curl --location --request PUT 'https://sync-core-api.otima.io/whatsapp/provider/workspace-templates/{uuid}' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {token}' \ --header 'x-workspace-uuid: {workspace_uuid}' \ --data '{ "category": "UTILITY", "components": [ { "type": "BODY", "text": "Olá {{1}}. Seu pedido foi atualizado." } ] }' ``` #### Exemplo de resposta (`200 OK`) ```json { "data": { "uuid": "{uuid}", "category": "UTILITY", "components": [ { "type": "BODY", "text": "Olá {{1}}. Seu pedido foi atualizado." } ] } } ``` *** #### Identificador oficial - UUID do template (OBRIGATÓRIO) Ao criar um template, a API retornará o **UUID do template**, que é o identificador único interno do sistema. Esse UUID deve ser utilizado como referência principal para todas as operações subsequentes relacionadas ao template, como: * exclusão * arquivamento * recuperação * atualização e demais ações de gerenciamento Dessa forma, o UUID garante consistência, rastreabilidade e integração com a Meta. Exemplo do formato uuid: ```http uuid: fb6cgb59-10aa-41ab-8c43-1820d5bb81df ``` *** #### Arquivar Template Arquiva um template existente na Meta. Templates arquivados: * deixam de aparecer como ativos * não podem mais ser utilizados em novos envios * permanecem armazenados para histórico O arquivamento é recomendado quando: * o template ficou obsoleto * será substituído por uma nova versão * não deve mais ser utilizado operacionalmente #### Endpoint de arquivamento: ```http POST https://sync-core-api.otima.io/whatsapp/provider/workspace-templates/{uuid}/archive ``` *** #### Recuperar Template Arquivado Remove o status de arquivado de um template e o torna disponível novamente para utilização. Ao recuperar um template: * ele volta para a lista de templates ativos * poderá ser utilizado novamente em envios * mantém suas configurações originais * preserva histórico e identificadores Esse processo é recomendado quando um template arquivado precisa voltar a ser utilizado operacionalmente sem necessidade de criar uma nova versão. #### Endpoint de recuperação: ```http POST https://sync-core-api.otima.io/whatsapp/provider/workspace-templates/{uuid}/unarchive ``` *** #### Excluir Template Remove permanentemente um template do sistema. {% hint style="danger" %} #### Importante * A exclusão é irreversível e remove completamente o template da plataforma e da Meta. Recomendado utilizar exclusão apenas quando: * o template foi criado incorretamente * nunca será reutilizado * não há necessidade de manter histórico Em cenários normais, prefira utilizar o arquivamento ao invés da exclusão. {% endhint %} #### Endpoint de exclusão: ```http DELETE https://sync-core-api.otima.io/whatsapp/provider/workspace-templates/{uuid} ``` *** #### Listar Templates (GET) Lista os templates do workspace, filtrando por business\_manager(BM), waba, status, categoria ou por nome do template(search). Filtro por BM: ```http https://sync-core-api.otima.io/whatsapp/provider/workspace-templates?business_id=272728392913901&status=APPROVED ``` Filtro por Waba: ```http https://sync-core-api.otima.io/whatsapp/provider/workspace-templates?waba_id=319392813736112 ``` Filtro por Status: ```http https://sync-core-api.otima.io/whatsapp/provider/workspace-templates?status=APPROVED ``` Filtro (search) nome do template: ```http https://sync-core-api.otima.io/whatsapp/provider/workspace-templates?search=revisao ``` **Parâmetros de filtros suportados:** | Parâmetro | Tipo | Descrição | | ------------ | ------ | ---------------------------------------------------------------------- | | business\_id | string | ID do Business Manager(BM) | | waba\_id | string | ID da conta WABA (WhatsApp Business Account) | | status | string | Filtra pelo status do template (ex: `APPROVED`, `PENDING`, `REJECTED`) | | category | string | Categoria do template (`marketing`, `utility`, `authentication`) | | search | string | Busca pelo nome do template | ### **Modelos de envios (POST)** Envia templates do workspace com HEADER (imagens, documentos e videos) ```http POST https://sync-core-api.otima.io/whatsapp/provider/{{NUMERO_AQUI}}/send-message ``` **Imagem:** ```json { "messaging_product": "whatsapp", "to": "554399999999", "type": "template", "template": { "name": "template_header_image", "language": { "code": "pt_BR" }, "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://site.com/imagem.jpg" } } ] }, { "type": "body", "parameters": [ { "type": "text", "text": "Jorge" } ] } ] } } ``` **Documento (PDF/XLS/DOC..):** ```json { "messaging_product": "whatsapp", "to": "554399999999", "type": "template", "template": { "name": "template_header_document", "language": { "code": "pt_BR" }, "components": [ { "type": "header", "parameters": [ { "type": "document", "document": { "link": "https://site.com/contrato.pdf", "filename": "contrato.pdf" } } ] }, { "type": "body", "parameters": [ { "type": "text", "text": "Carlos" } ] } ] } } ``` **Video:** ```json { "messaging_product": "whatsapp", "to": "5543999999999", "type": "template", "template": { "name": "template_header_video", "language": { "code": "pt_BR" }, "components": [ { "type": "header", "parameters": [ { "type": "video", "video": { "link": "https://site.com/video.mp4" } } ] }, { "type": "body", "parameters": [ { "type": "text", "text": "Luis" } ] } ] } } ``` Modelos template FOOTER: ```json { "messaging_product": "whatsapp", "to": "554399999999", "type": "template", "template": { "name": "template_footer", "language": { "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "Bruna" } ] }, { "type": "footer", "parameters": [ { "type": "text", "text": "Equipe Financeiro" } ] } ] } } ``` *** ### **Metadados Personalizados** ### biz\_opaque\_callback\_data O campo `biz_opaque_callback_data` é utilizado para enviar **metadados personalizados** junto com a mensagem/template no envio via API do WhatsApp. Esses dados: * **não aparecem para o usuário final** * são **retornados nos webhooks de status** (sent, delivered, read, failed) * servem para **correlacionar mensagens com registros internos** (ex: CRM, deals, contatos, logs) *** ### Quando usar Use `biz_opaque_callback_data` quando precisar: * identificar **qual contato/deal originou o envio** * rastrear mensagens em sistemas internos * evitar depender apenas do `message_id` da Meta *** #### Formato O valor deve ser uma **string JSON serializada (stringify)**. {% hint style="danger" %} #### Importante * Não envie objeto direto * Sempre envie como **string válida** * Escape corretamente as aspas (`\"`) {% endhint %} *** #### Exemplo de uso **Payload com template + callback data** ```json { "messaging_product": "whatsapp", "to": "5543999999999", "type": "template", "biz_opaque_callback_data": "{\"contact_id\":\"114792693\",\"deal_id\":\"67114640\",\"source\":\"crm\"}", "template": { "name": "template_header_video", "language": { "code": "pt_BR" }, "components": [ { "type": "header", "parameters": [ { "type": "video", "video": { "link": "https://site.com/video.mp4" } } ] }, { "type": "body", "parameters": [ { "type": "text", "text": "Luis" } ] } ] } } ``` *** ### Alguns exemplos de modelos para envio de templates: **Quick Reply, CTA e Carrossel**. Todos os modelos são **100% compatíveis com o padrão JSON da Meta**, permitindo utilizar todos os tipos de envio oferecidos pela Meta. #### Template Quick Reply {% code overflow="wrap" expandable="true" %} ```json { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "{{to}}", "type": "template", "biz_opaque_callback_data": "{{callback}}", "template": { "name": "template_quick_rep", "language": { "code": "pt_BR" }, "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "{{image}}" } } ] }, { "type": "body", "parameters": [ { "type": "text", "text": "Jorge" }, { "type": "text", "text": "50%" } ] }, { "type": "button", "sub_type": "quick_reply", "index": "0", "parameters": [ { "type": "payload", "payload": "confirmar" } ] }, { "type": "button", "sub_type": "quick_reply", "index": "1", "parameters": [ { "type": "payload", "payload": "encerrar" } ] }, { "type": "button", "sub_type": "quick_reply", "index": "2", "parameters": [ { "type": "payload", "payload": "falar_com_atendente" } ] } ] } } ``` {% endcode %} #### Template CTA {% code overflow="wrap" expandable="true" %} ```json { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "{{to}}", "type": "template", "biz_opaque_callback_data": "{{callback}}", "template": { "name": "template_cta_documento", "language": { "code": "pt_BR" }, "components": [ { "type": "header", "parameters": [ { "type": "document", "document": { "link": "{{document}}", "filename": "{{document_filename}}" } } ] }, { "type": "body", "parameters": [ { "type": "text", "text": "Jorge" }, { "type": "text", "text": "07062026" } ] } ] } } ``` {% endcode %} #### Template Carrossel {% code overflow="wrap" expandable="true" %} ```json { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "{{to}}", "type": "template", "biz_opaque_callback_data": "{{callback}}", "template": { "name": "template_carrossel_oferta", "language": { "code": "pt_BR" }, "components": [ { "type": "body", "parameters": [ { "type": "text", "text": "Jorge" }, { "type": "text", "text": "R$10,00" }, { "type": "text", "text": "70% OFF" } ] }, { "type": "button", "sub_type": "quick_reply", "index": "0", "parameters": [ { "type": "payload", "payload": "falar_com_atendente" } ] }, { "type": "carousel", "cards": [ { "card_index": 0, "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "{{image}}" } } ] }, { "type": "button", "sub_type": "quick_reply", "index": "0", "parameters": [ { "type": "payload", "payload": "carousel_oferta_1" } ] } ] }, { "card_index": 1, "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "{{image}}" } } ] }, { "type": "button", "sub_type": "quick_reply", "index": "0", "parameters": [ { "type": "payload", "payload": "carousel_oferta_2" } ] } ] }, { "card_index": 2, "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "{{image}}" } } ] }, { "type": "button", "sub_type": "quick_reply", "index": "0", "parameters": [ { "type": "payload", "payload": "carousel_oferta_3" } ] } ] } ] } ] } } ``` {% endcode %} *** ### Exemplo no Webhook de Status Quando o WhatsApp retornar o status da mensagem, o campo virá assim: ```json { "statuses": [ { "id": "wamid.HBgM...", "status": "delivered", "biz_opaque_callback_data": "{\"contact_id\":\"114792693\",\"deal_id\":\"67114640\",\"source\":\"crm\"}" } ] } ``` *** {% hint style="success" %} #### Boas práticas * Use IDs internos (ex: `contact_id`, `deal_id`) * Mantenha o payload pequeno (evitar excesso de dados) * Sempre valide e faça parse do JSON no webhook {% endhint %}