Modelos
Gerencie os modelos usados por uma conta: seus modelos de e-mail, cabeçalhos e modelos DLT de SMS e seu número e modelos do WhatsApp. A leitura exige o escopo de envio do canal ou templates:manage; alterações exigem uma chave Owner ou Admin com templates:manage.
Estas rotas /external/v1 usam chaves de API. Os tokens de acesso OAuth usam a API v2; a existência de um exemplo não comprova que uma implantação esteja configurada para essa versão.
Modelos de e-mail
Os modelos de e-mail da conta são os de seu espaço de trabalho padrão, onde ficam as mensagens da API e onde o painel os lista. Um modelo criado pela API contém HTML com marcadores {{name}} preenchidos no envio. Um modelo criado no editor do painel pode ser consultado, usado para enviar e excluído, mas não substituído, mantendo o HTML e o projeto consistentes.
| Método | Caminho | Função |
|---|---|---|
GET | /external/v1/templates | Os modelos, do mais recente para o mais antigo, sem seu HTML |
GET | /external/v1/templates/{id} | Um modelo, com seu HTML e as variáveis esperadas |
POST | /external/v1/templates | Cria um modelo a partir de HTML: 201 |
PUT | /external/v1/templates/{id} | Substitui um modelo criado a partir de HTML: nome, assunto e HTML |
DELETE | /external/v1/templates/{id} | Exclui um modelo: 204; ele deixa de ser listado e usado para enviar |
- Nome
name- Tipo
- string
- Descrição
Obrigatório: o nome do modelo, com no máximo 255 caracteres. A validação padrão de nomes do Oblic também se aplica; respeitar apenas o tamanho não basta.
- Nome
subject- Tipo
- string
- Descrição
O assunto usado por um e-mail enviado com o modelo quando o envio não informa um, com no máximo 1,023 caracteres e seus próprios marcadores. Um assunto omitido ou vazio é armazenado como
null; espaços no início e no fim de um assunto não vazio são removidos.
- Nome
html- Tipo
- string
- Descrição
Obrigatório: o HTML, armazenado como fornecido, com no máximo 65,535 bytes UTF-8. Os valores das variáveis recebem escape de HTML quando o envio preenche os marcadores; isso não sanitiza nem isola o HTML do modelo em uma sandbox.
Criar um modelo
curl -X POST https://api.oblic.app/external/v1/templates \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "Order shipped",
"subject": "Order {{order_id}} is on its way",
"html": "<p>Hi {{first_name}}, your order {{order_id}} has shipped.</p>"
}'
201 Criado
{
"status": "success",
"data": {
"id": "TEM000R7ZM4Q2VXH00",
"name": "Order shipped",
"subject": "Order {{order_id}} is on its way",
"kind": "html",
"variables": ["order_id", "first_name"],
"html": "<p>Hi {{first_name}}, your order {{order_id}} has shipped.</p>",
"createdAt": "2026-10-24T09:30:00Z",
"updatedAt": "2026-10-24T09:30:00Z"
},
"errors": null
}
- Um marcador é
{{name}}: letras e dígitos ASCII,_,.,-e espaços apenas dentro do nome, com no máximo 64 caracteres.variableslista os marcadores do assunto e do HTML sem diferenciar maiúsculas de minúsculas, na ordem e com a grafia da primeira ocorrência. kindéhtmlpara um modelo criado pela API edesignedpara um criado no editor do painel. Se o modelo não tiver assunto, informe um no envio; seu tipo não substitui a verificação do assunto retornado.- As menções do painel, como
@unsubscribeou@organizationName, só são preenchidas por campanhas e automações para cada destinatário. Um envio com um modelo que contenha uma delas é recusado. - A lista é paginada por
cursorelimit: 25 itens por página por padrão, de 1 a 100, conforme Paginação. Trate o cursor retornado como um valor opaco.
| Recusa | cd | Quando |
|---|---|---|
| 400 | TEMPLATE_TOO_LARGE | O HTML ultrapassa 65,535 bytes |
| 404 | TEMPLATE_NOT_FOUND | A conta não tem um modelo com esse identificador |
| 409 | TEMPLATE_DESIGNED | Substituição de um modelo criado no editor do painel |
Cabeçalhos e modelos de SMS
Um SMS usa um cabeçalho DLT e corresponde a um modelo de conteúdo DLT da entidade DLT configurada da Cunomial. Ambos são registrados primeiro em uma plataforma DLT e depois cadastrados aqui para associação a um envio de SMS. Cadastrá-los aqui não os registra na DLT. Na resposta da conta SMS, keepsRegistry e available descrevem a permissão e a disponibilidade do registro configurado, não uma promessa de entrega.
Somente modelos aprovados do registro são listados; modelos aprovados inativos ainda podem aparecer. Um envio também exige um modelo ativo e as demais verificações descritas em Mensagens.
| Método | Caminho | Função |
|---|---|---|
GET | /external/v1/sms/account | Limites da conta, envios do mês e tipos de mensagem permitidos |
GET | /external/v1/sms/senders | Os cabeçalhos próprios da conta, [{"senderId": …, "isDefault": …}] |
PUT | /external/v1/sms/senders/{senderId} | Adiciona um cabeçalho de seis letras ou seis dígitos; {"isDefault": true} o define como padrão |
DELETE | /external/v1/sms/senders/{senderId} | Exclui um cabeçalho que nenhum modelo usa: 204 |
GET | /external/v1/sms/templates | Os modelos da conta, seguidos dos compartilhados pela conta principal |
POST | /external/v1/sms/templates | Adiciona um modelo: 201 |
PUT | /external/v1/sms/templates/{id} | Altera um modelo fornecido integralmente |
DELETE | /external/v1/sms/templates/{id} | Exclui um modelo: 204 |
PUT | /external/v1/sms/templates/{id}/sharing | Permite que nenhuma, todas ou as subcontas indicadas o usem para enviar |
- Nome
templateId- Tipo
- string
- Descrição
Obrigatório: o identificador DLT do modelo, com até 32 dígitos.
- Nome
senderId- Tipo
- string
- Descrição
Obrigatório: um cabeçalho da conta. Um modelo promocional usa um cabeçalho de seis dígitos; os demais usam um de seis letras.
- Nome
name- Tipo
- string
- Descrição
Obrigatório: um nome de sua escolha, com no máximo 80 caracteres.
- Nome
body- Tipo
- string
- Descrição
Obrigatório: o texto registrado na DLT, com no máximo 2,000 caracteres e cada variável como
{#var#}, até 30 variáveis.
- Nome
variableKeys- Tipo
- string[]
- Descrição
Um nome para cada variável, em ordem, como
["otp", "minutes"]. Se omitido ou vazio, são usados os nomes posicionais de1an. Se informados, os nomes devem ser únicos e conter letras ou dígitos ASCII ou_, com 1 a 30 caracteres cada; a quantidade deve corresponder ao número de variáveis.
- Nome
type- Tipo
- string
- Descrição
Obrigatório: o tipo DLT,
transactional,service_implicit,service_explicitoupromotional.
- Nome
unicode- Tipo
- boolean
- Descrição
Indica se o texto é Unicode;
falsepor padrão.
- Nome
active- Tipo
- boolean
- Descrição
Indica se o envio é permitido;
truepor padrão.
Adicionar um modelo
curl -X POST https://api.oblic.app/external/v1/sms/templates \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"templateId": "1107161234567890123",
"senderId": "EXMPLE",
"name": "Sign-in code",
"body": "Your Example code is {#var#}. It is valid for {#var#} minutes.",
"variableKeys": ["code", "minutes"],
"type": "service_implicit"
}'
- Somente as contas para as quais o Oblic registra SMS adicionam e alteram cabeçalhos e modelos; as demais recebem
403 REGISTRY_NOT_ALLOWEDe usam os modelos compartilhados com elas. - O compartilhamento aceita
{"scope": "none" | "all" | "selected", "accounts": […]}, com no máximo 1,000 valoresexternalIdde subcontas paraselected. Cada conta indicada deve pertencer à principal. Uma seleção vazia não compartilha com nenhuma subconta. - A definição padrão de um cabeçalho é estabelecida em cada
PUT: sem"isDefault": true, o cabeçalho não fica como padrão. Definir um como padrão remove essa condição do anterior da conta.
| Recusa | cd | Quando |
|---|---|---|
| 400 | INVALID_TEMPLATE | O cabeçalho não corresponde ao tipo, existem mais de 30 variáveis ou variableKeys não nomeia cada uma exatamente uma vez |
| 403 | REGISTRY_NOT_ALLOWED | A conta não registra SMS próprios |
| 404 | TEMPLATE_NOT_FOUND, SENDER_NOT_FOUND, ACCOUNT_NOT_FOUND | Modelo, cabeçalho ou subconta inexistente |
| 409 | TEMPLATE_EXISTS | Já existe um modelo registrado com esse identificador DLT |
| 409 | SENDER_IN_USE | Exclusão de um cabeçalho usado por modelos |
| 422 | SENDER_NOT_ALLOWED | O cabeçalho não pertence à conta |
| 422 | MESSAGE_TYPE_NOT_ENABLED | O tipo do modelo não é enviado pelo Oblic: messageTypes da conta, apenas service_implicit por padrão |
Número e modelos do WhatsApp
Uma mensagem do WhatsApp sai do número WhatsApp Business conectado da conta, usando um modelo aprovado pela Meta.
| Método | Caminho | Função |
|---|---|---|
POST | /external/v1/whatsapp/connection | Conecta o número ou substitui o conectado |
GET | /external/v1/whatsapp/connection | O número conectado; 404 WHATSAPP_NOT_CONNECTED quando ausente |
DELETE | /external/v1/whatsapp/connection | Desconecta o número: 204 |
GET | /external/v1/whatsapp/templates | Os modelos com a análise da Meta de cada um |
POST | /external/v1/whatsapp/templates | Envia um modelo à Meta para análise: 201 |
GET | /external/v1/whatsapp/recipients/{number} | O que a conta pode enviar a um número agora |
A conexão usa o resultado do Embedded Signup executado com o aplicativo Meta do Oblic: code, phoneNumberId, wabaId, opcionalmente businessId, e o pin de seis dígitos usado para registrar o número. O status da resposta é INTEGRATED quando todas as etapas são confirmadas; uma conexão interrompida permanece PENDING. Tente novamente com dados de cadastro válidos; não há garantia de que um código usado ou expirado funcione outra vez. Se a Meta recusar uma etapa, a resposta é 502, com seu código, como WHATSAPP_REGISTER_REFUSED, sem retornar o corpo bruto da resposta.
- Nome
name- Tipo
- string
- Descrição
Obrigatório: letras ASCII minúsculas, dígitos e
_, comoorder_shipped. O nome expandido pelo Oblic, qualificado por conta e idioma, deve ter no máximo 100 caracteres; exceder esse limite é recusado antes de chamar a Meta. Use onameretornado ao enviar, sem presumir que o nome curto informado seja o armazenado pela Meta.
- Nome
language- Tipo
- string
- Descrição
Idioma do modelo: duas letras ASCII minúsculas, opcionalmente
_e duas letras ASCII maiúsculas, comoen,hiouen_US;enquando omitido. Um nome pode ter um modelo por idioma; repetir o mesmo nome e idioma gera conflito.
- Nome
category- Tipo
- string
- Descrição
Obrigatório:
MARKETING,UTILITYouAUTHENTICATION.
- Nome
components- Tipo
- object[]
- Descrição
Obrigatório: cabeçalho, corpo, rodapé e botões do modelo, no formato da Meta, com exemplos de suas variáveis.
Enviar um modelo para análise
curl -X POST https://api.oblic.app/external/v1/whatsapp/templates \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "order_shipped",
"language": "en",
"category": "UTILITY",
"components": [
{
"type": "BODY",
"text": "Hi {{1}}, your order {{2}} has shipped.",
"example": { "body_text": [["Asha", "1042"]] }
}
]
}'
- O
statusde um modelo é o estado de análise armazenado da Meta, por exemploPENDING,APPROVEDouREJECTED;rejectionReasonpode estar ausente.201significa enviado para análise, não aprovado. Só modelosAPPROVEDpodem ser enviados. Não há prazo prometido para concluir a análise. - Um destinatário retorna
number,optedOut, quando e como (optedOutAt,optOutSource),lastInboundAtesessionOpenUntil: a janela de 24 horas desde a última mensagem recebida da pessoa.optedOutse refere a marketing, não a todas as mensagens. Sem histórico recebido,lastInboundAtesessionOpenUntilsãonull. Um horário de sessão, sozinho, não garante que o envio seja aceito: as demais verificações continuam valendo.
| Recusa | cd | Quando |
|---|---|---|
| 409 | TEMPLATE_EXISTS | A conta tem um modelo com esse nome nesse idioma |
| 422 | WHATSAPP_NOT_CONNECTED | Envio de um modelo para análise sem número conectado |
| 422 | TEMPLATE_NAME_TOO_LONG | O nome é longo demais para a Meta |
| 422 | TEMPLATE_REFUSED | A Meta recusou o modelo; recusa genérica localizada, não o texto bruto da resposta da Meta |
| 422 | INVALID_NUMBER | O número do destinatário não está no formato internacional |
| 502 | WHATSAPP_CODE_REFUSED, WHATSAPP_SUBSCRIBE_REFUSED, WHATSAPP_REGISTER_REFUSED | A Meta recusou uma etapa da conexão do número |
| 503 | WHATSAPP_UNAVAILABLE | Não foi possível contatar a Meta durante uma etapa de conexão |