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.


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étodoCaminhoFunção
GET/external/v1/templatesOs 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/templatesCria 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. variables lista 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 é html para um modelo criado pela API e designed para 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 @unsubscribe ou @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 cursor e limit: 25 itens por página por padrão, de 1 a 100, conforme Paginação. Trate o cursor retornado como um valor opaco.
RecusacdQuando
400TEMPLATE_TOO_LARGEO HTML ultrapassa 65,535 bytes
404TEMPLATE_NOT_FOUNDA conta não tem um modelo com esse identificador
409TEMPLATE_DESIGNEDSubstituiçã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étodoCaminhoFunção
GET/external/v1/sms/accountLimites da conta, envios do mês e tipos de mensagem permitidos
GET/external/v1/sms/sendersOs 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/templatesOs modelos da conta, seguidos dos compartilhados pela conta principal
POST/external/v1/sms/templatesAdiciona 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}/sharingPermite 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 de 1 a n. 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_explicit ou promotional.

  • Nome
    unicode
    Tipo
    boolean
    Descrição

    Indica se o texto é Unicode; false por padrão.

  • Nome
    active
    Tipo
    boolean
    Descrição

    Indica se o envio é permitido; true por 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_ALLOWED e usam os modelos compartilhados com elas.
  • O compartilhamento aceita {"scope": "none" | "all" | "selected", "accounts": […]}, com no máximo 1,000 valores externalId de subcontas para selected. 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.
RecusacdQuando
400INVALID_TEMPLATEO cabeçalho não corresponde ao tipo, existem mais de 30 variáveis ou variableKeys não nomeia cada uma exatamente uma vez
403REGISTRY_NOT_ALLOWEDA conta não registra SMS próprios
404TEMPLATE_NOT_FOUND, SENDER_NOT_FOUND, ACCOUNT_NOT_FOUNDModelo, cabeçalho ou subconta inexistente
409TEMPLATE_EXISTSJá existe um modelo registrado com esse identificador DLT
409SENDER_IN_USEExclusão de um cabeçalho usado por modelos
422SENDER_NOT_ALLOWEDO cabeçalho não pertence à conta
422MESSAGE_TYPE_NOT_ENABLEDO 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étodoCaminhoFunção
POST/external/v1/whatsapp/connectionConecta o número ou substitui o conectado
GET/external/v1/whatsapp/connectionO número conectado; 404 WHATSAPP_NOT_CONNECTED quando ausente
DELETE/external/v1/whatsapp/connectionDesconecta o número: 204
GET/external/v1/whatsapp/templatesOs modelos com a análise da Meta de cada um
POST/external/v1/whatsapp/templatesEnvia 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 _, como order_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 o name retornado 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, como en, hi ou en_US; en quando 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, UTILITY ou AUTHENTICATION.

  • 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 status de um modelo é o estado de análise armazenado da Meta, por exemplo PENDING, APPROVED ou REJECTED; rejectionReason pode estar ausente. 201 significa enviado para análise, não aprovado. Só modelos APPROVED podem ser enviados. Não há prazo prometido para concluir a análise.
  • Um destinatário retorna number, optedOut, quando e como (optedOutAt, optOutSource), lastInboundAt e sessionOpenUntil: a janela de 24 horas desde a última mensagem recebida da pessoa. optedOut se refere a marketing, não a todas as mensagens. Sem histórico recebido, lastInboundAt e sessionOpenUntil são null. Um horário de sessão, sozinho, não garante que o envio seja aceito: as demais verificações continuam valendo.
RecusacdQuando
409TEMPLATE_EXISTSA conta tem um modelo com esse nome nesse idioma
422WHATSAPP_NOT_CONNECTEDEnvio de um modelo para análise sem número conectado
422TEMPLATE_NAME_TOO_LONGO nome é longo demais para a Meta
422TEMPLATE_REFUSEDA Meta recusou o modelo; recusa genérica localizada, não o texto bruto da resposta da Meta
422INVALID_NUMBERO número do destinatário não está no formato internacional
502WHATSAPP_CODE_REFUSED, WHATSAPP_SUBSCRIBE_REFUSED, WHATSAPP_REGISTER_REFUSEDA Meta recusou uma etapa da conexão do número
503WHATSAPP_UNAVAILABLENão foi possível contatar a Meta durante uma etapa de conexão
Esta página foi útil?