# API Templates

# Headers Obrigatórios

Header Tipo Obrigatório Descrição
authorization Authorization Bearer Token ✔️ A chave da sua API
accept application/json ✔️

# Buscar um template pelo o _id

Para buscar um template pelo o _id, será necessário fazer um requisição do tipo GET para a API da seguinte forma:

  GET https://voyager.smarttalks.ai/v1/templates/[ _id ]
Parâmetro Tipo Obrigatório Descrição
_id ObjectID Indentificador do template
curl -X GET https://voyager.smarttalks.ai/v1/templates/62b1e3233ea95a9f3e97f050  \
  -H 'Content-Type: application/json'
     'Authorization: "{{apiToken}}"'
Exemplo de retorno:

{
  "_id": "62b1e3233ea95a9f3e97f050",
  "status": true,
  "groupId": "624f20077714b7625f027fe3",
  "accountId": "624f45692cd11e345170bfd1",
  "namespace": "10bcdc26_7c28_4a7b_94f7_c355d67302ad",
  "templateName": "campanha",
  "name": "campanha",
  "language": "pt_BR",
  "policy": "deterministic",
  "components": [
    {
      "type": "BODY",
      "text": "Oi {{1}}! Sem Planos para comemorar o Dia dos Namorados? Que tal surpreender seu amor e irem viver uma experiência gastronômica inesquecível? Confira o que o Restaurante Izi, localizado no Hotel Guide preparaou para vocês! Ah, e não precisa estar hospedado, o restaurante é aberto ao público Reserve já, último lugares",
      "_id": "62b1e3233ea95a9f3796f051",
      "buttons": []
    }
  ],
  "statusTemplate": "APPROVED",
  "category": "ACCOUNT_UPDATE",
  "createdAt": "2022-06-21T15:26:27.987Z",
  "updatedAt": "2022-06-21T15:26:27.987Z",
  "__v": 0,
  "hasVariables": true,
  "numberOfVariables": 1,
  "createdBy": "629a3d752ef1530b1878cfaf",
  "updatedBy": "629a3d752ef1530b1878cfaf",
  "channelId": "636c0537966c7471909e2a0a",
  "channel": "whatsapp"
}


# Buscar templates

  POST https://voyager.smarttalks.ai/v1/templates

Para buscar templates será necessário fazer uma requisição do tipo POST para a API. No corpo da requisição pode ser passado as seguintes propriedades, que são do tipo objeto:

# query e project

Parâmetro Tipo Descrição
_id ObjectID ID do template
createdAt Date Data em que o template foi criado
Status Boolean Status do template se está ativo
groupId ObjectID ID do grupo
accountId ObjectID ID da conta
components Array Componentes presente no template: Body, Header, Footer , Buttons
nameSpace String ID do template para o whatsapp
templateName string Nome do template, seguindo a regra do whatspapp
name String Nome do template
language String Idioma do template
policy String Politica
statusTemplate String Status template para o whatsapp
channel String Canal
channelId ObjectID Canal que o template pertence
category String Categoria
hasVariables Boolean Tem váriaveis
numberOfVariables Number Número de váriaveis

# options usado para paginação

Propriedade Tipo Default Descrição
skip Number Registro a pular
limit Number 10 Quantidade de registro a retorno
curl -X POST https://voyager.smarttalks.ai/v1/templates \
  -H 'Content-Type: application/json'
     'accept: application/json'\
     'Authorization: "{{apiToken}}"'
  -d '{ "query": { "_id": "62b1e3233ea95a9f3e97f050" }, "project": { "name": 1, "language": 1, "components": 1, "statusTemplate": 1, "category": 1, "channel": 1 }, "options": { "skip": 0, "limit": 1 } }'
Exemplo de retorno:
[
  {
    "_id": "62b1e3233ea95a9f3e97f050",
    "name": "campanha",
    "language": "pt_BR",
    "components": [
      {
        "type": "BODY",
        "text": "Oi {{1}}! Sem Planos para comemorar o Dia dos Namorados? Que tal surpreender seu amor e irem viver uma experiência gastronômica inesquecível? Confira o que o Restaurante Izi, localizado no Hotel Guide preparaou para vocês! Ah, e não precisa estar hospedado, o restaurante é aberto ao público Reserve já, último lugares",
        "_id": "62b1e3233ea95a9f3796f051",
        "buttons": []
      }
    ],
    "statusTemplate": "APPROVED",
    "category": "ACCOUNT_UPDATE",
    "channel": "whatsapp"
  }
]

# Enviar template

  POST https://voyager.smarttalks.ai/v1/messages

Para enviar um template/HSM para um contato é necessário fazer uma requisição do tipo POST, com os seguintes dados no corpo da requisição.

Parâmetro Tipo Descrição
_id ObjectID ID do template
type String Tipo de envio
to String Telefone/Whatsapp para receber a mensagem
overwriteUnit Boolean Define se a unidade enviada em unit deve substituir (true) ou apenas ser adicionada à lista existente (false). Valor padrão: true
tagId String Tag a ser adicionada na interação
unit String Id da unidade a ser associada ao contato
flowId ObjectID Identificador do fluxo (flow) a ser associado à interação.
blockId ObjectID Identificador do bloco (block) a ser associado à interação. Requer flowId.
components Array Variáveis a serem substituidas no template, obrigatório se o template contém variável ou algum tipo de mídia(image/video/document)

# Exemplo com variável no corpo ou no cabeçalho

curl -X POST https://voyager.smarttalks.ai/v1/messages \
  -H 'Content-Type: application/json'
     'accept: application/json'\
     'Authorization: "{{apiToken}}"'
  -d '{ "_id": "62fff7b334ff67a362a962", "type": "template", "to": "5500000000000", "tagId": "68347f225bf315231563a99f", "unit": "646518143291581f467aacf7", "flowId": "65b2d9f2e4b0a82b8c8d8e8f", "blockId": "65b2d9f2e4b0a82b8c8d8e90", "components": [{ "type": "body","parameters": [ { "type": "text", "text": "John" }, { "type": "text", "text": "1234abcd" } ], { "type": "header","parameters": [ { "type": "text", "text": "John" }]}] }'
Exemplo de retorno:
{
 "interactionId": "63b3968f4f987a8b65c430",
 "contact": "559281549159"
}

# Exemplo com variável no botão:

Para enviar templates que tenha botão do tipo URL com variável, deve ser enviado da seguinte forma:

  • o index é de acordo com a posição que o botão está, como o botão url só pode estar acompanhado com o botão do tipo telefone, então só pode ter dois botões, se ele vier primeiro o index é 0, se ele vier depois do botão de telefone o index vai ser 1.
{
  "_id": "62fff7b334ff67a362a962",
  "type": "template",
  "to": "5500000000000",
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "John"
        },
        {
          "type": "text",
          "text": "1234abcd"
        }
      ]
    },
    {
      "type": "button",
      "sub_type": "url",
      "index": 1,
      "parameters": [
        {
          "type": "text",
          "text": "blog"
        }
      ]
    }
  ]
}
curl -X POST https://voyager.smarttalks.ai/v1/messages \
  -H 'Content-Type: application/json'
     'accept: application/json'\
     'Authorization: "{{apiToken}}"'
  -d '{ "_id": "62fff7b334ff67a362a962", "type": "template", "to": "5500000000000", "components": [{ "type": "body","parameters": [ { "type": "text", "text": "John" }, { "type": "text", "text": "1234abcd" } ]}, { "type": "button", "sub_type": "url", "index": 1, "parameters": [ { "type": "text", "text": "blog" } ] } ] }'
Exemplo de retorno:
{
 "interactionId": "63b3968f4f987a8b65c430",
 "contact": "559281549159"
}

# Exemplo com template de autenticação:

O template de autenticação (categoria AUTHENTICATION) entrega um código de verificação pelo WhatsApp, por exemplo para liberar o acesso a um aplicativo. O seu sistema gera e valida o código; a plataforma só o entrega. O envio é feito somente por esta API.

  • envie o mesmo código no corpo e no botão de copiar código, que é o botão de índice 0;
  • o código deve ter até 15 caracteres;
  • sem o código, com códigos diferentes ou com mais de 15 caracteres, a API responde 400, e message traz o motivo;
  • o código não fica registrado na conversa nem nas métricas de envio;
  • ao reenviar um código (por exemplo no botão "reenviar código" do seu aplicativo), mande um X-Idempotency-Key novo a cada envio: um UUID gerado para aquele envio. A chave precisa ser única globalmente, não só na sua conta, então evite valores previsíveis como o id do usuário. Sem essa chave, um segundo envio do mesmo template para o mesmo número em até 10 segundos devolve a resposta do primeiro envio, com o status dele (inclusive um erro), e não envia nada, e a pessoa fica com o código antigo. Enquanto o primeiro envio ainda está em andamento (até 30 segundos), um envio igual recebe 409. Depois de corrigir um envio recusado, também use uma chave nova. Repetir a mesma chave devolve a resposta anterior, sem enviar de novo, por 5 minutos.
{
  "_id": "62fff7b334ff67a362a962",
  "type": "template",
  "to": "5500000000000",
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "482913"
        }
      ]
    },
    {
      "type": "button",
      "sub_type": "url",
      "index": 0,
      "parameters": [
        {
          "type": "text",
          "text": "482913"
        }
      ]
    }
  ]
}
curl -X POST https://voyager.smarttalks.ai/v1/messages \
  -H 'Content-Type: application/json'
     'accept: application/json'\
     'Authorization: "{{apiToken}}"'\
     'X-Idempotency-Key: "{{uuidDoEnvio}}"'
  -d '{ "_id": "62fff7b334ff67a362a962", "type": "template", "to": "5500000000000", "components": [{ "type": "body", "parameters": [ { "type": "text", "text": "482913" } ] }, { "type": "button", "sub_type": "url", "index": 0, "parameters": [ { "type": "text", "text": "482913" } ] } ] }'
Exemplo de retorno:
{
 "interactionId": "63b3968f4f987a8b65c430",
 "contact": "559281549159"
}

# Exemplo com mídia:

{
  "_id": "62fff7b334ff67a362a962",
  "type": "template",
  "to": "5500000000000",
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "John"
        },
        {
          "type": "text",
          "text": "1234abcd"
        }
      ]
    },
    {
      "type": "header",
      "parameters": [
        {
          "type": "image",
          "image": {
            "link": "https://example.com/image.jpeg"
          }
        }
      ]
    }
  ]
}
curl -X POST https://voyager.smarttalks.ai/v1/messages \
  -H 'Content-Type: application/json'
     'accept: application/json'\
     'Authorization: "{{apiToken}}"'
  -d '{ "_id": "62fff7b334ff67a362a962", "type": "template", "to": "5500000000000", "components": [{ "type": "body","parameters": [ { "type": "text", "text": "John" }, { "type": "text", "text": "1234abcd" } ]}, { "type": "button", "sub_type": "url", "index": 1, "parameters": [ { "type": "text", "text": "blog" } ] }, { "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://example.com/image.jpeg" } } ] } ] }'
Exemplo de retorno:
{
 "interactionId": "63b3968f4f987a8b65c430",
 "contact": "559281549159"
}