Envio Individual (1-1) - Jelou AI Docs

Send Individual HSM

curl --request POST \
  --url https://api.jelou.ai/v2/whatsapp/{botId}/hsm \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "elementName": "<string>",
  "destinations": [
    "<string>"
  ],
  "mediaUrl": "<string>",
  "filename": "<string>",
  "type": "text",
  "parameters": [
    "<string>"
  ],
  "buttonPayloads": [
    {}
  ],
  "actions": {},
  "headerParameters": [
    "<string>"
  ],
  "buttonParameters": [
    {
      "payload": {},
      "param": 123
    }
  ],
  "ltoParams": {
    "expirationTime": 123
  },
  "cards": [
    {
      "mediaUrl": "<string>",
      "params": [
        "<string>"
      ],
      "buttonParameters": [
        {
          "payload": {},
          "param": 123
        }
      ]
    }
  ],
  "expirationTime": "<string>",
  "campaignId": "<string>"
}
'

[
  {
    "id": "<string>",
    "destination": "<string>"
  }
]

POST

{botId}

hsm

Send Individual HSM

curl --request POST \
  --url https://api.jelou.ai/v2/whatsapp/{botId}/hsm \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "elementName": "<string>",
  "destinations": [
    "<string>"
  ],
  "mediaUrl": "<string>",
  "filename": "<string>",
  "type": "text",
  "parameters": [
    "<string>"
  ],
  "buttonPayloads": [
    {}
  ],
  "actions": {},
  "headerParameters": [
    "<string>"
  ],
  "buttonParameters": [
    {
      "payload": {},
      "param": 123
    }
  ],
  "ltoParams": {
    "expirationTime": 123
  },
  "cards": [
    {
      "mediaUrl": "<string>",
      "params": [
        "<string>"
      ],
      "buttonParameters": [
        {
          "payload": {},
          "param": 123
        }
      ]
    }
  ],
  "expirationTime": "<string>",
  "campaignId": "<string>"
}
'

[
  {
    "id": "<string>",
    "destination": "<string>"
  }
]

A API WhatsApp permite que empresas automatizem e personalizem a comunicação com seus clientes, possibilitando interações eficientes e escaláveis enriquecidas com conteúdo multimídia. É ideal para gerenciar consultas, enviar notificações e fornecer respostas imediatas por meio de Agentes de IA.

Configuração do envio de mensagens

Passo 1: Definir o Endpoint

Para enviar mensagens, use o seguinte endpoint da API:

POST https://api.jelou.ai/v2/whatsapp/{botId}/hsm

Passo 2: Parâmetros da Requisição

Os principais parâmetros da requisição incluem:

Text: O conteúdo da mensagem.
Tipo de mensagem (type): Define o tipo de template a ser enviado.
Propriedade do template: Template previamente criado e aprovado pela META.
Arquivo de mídia: Se o template exigir uma URL (imagem, documento, etc.).
Bot ID: Identificador único do bot.
Parâmetros: Dados específicos para cada envio (nome, número do pedido, etc.).

Passo 3: Enviar a requisição

Envie a mensagem usando o método POST. Após concluir o envio, você receberá uma resposta que permite verificar o status de entrega.

Certifique-se de cumprir as políticas do WhatsApp para evitar restrições.

Restrições de conteúdo

Lembre-se de que, para enviar mensagens pelo WhatsApp, você deve usar templates previamente aprovados pela META. Cada template tem limitações específicas com base em seu formato e conteúdo, como o comprimento da mensagem ou o tipo de informação permitida. Certifique-se de revisar essas restrições antes de usá-los para garantir a entrega correta. Tenha em mente que:

URLs, emojis e arquivos multimídia não são permitidos em mensagens de autenticação.
Os parâmetros devem ter no máximo 15 caracteres.

Corpo da Requisição

Propriedade	Tipo	Descrição	Obrigatório
mediaUrl	string	URL pública do arquivo de mídia. Obrigatório se o seu template for do tipo vídeo, imagem ou documento.	Condicional
filename	string	Nome do arquivo para templates do tipo documento.	Condicional
type	string	Tipo de mensagem: `text`, `hsm`, `image`, `document`, `video`, `catalog`, `carousel`. Padrão é `text`.	Não
language	string	Idioma do template: `en`, `es`, `pt`	Não
elementName	string	Nome do template aprovado.	Sim
parameters	array	Conjunto de strings que substituem valores no template.	Sim
destinations	array	Lista de números de telefone. Formato numérico com código do país, sem `+` ou espaços.	Sim
buttonPayloads	array	Informações para botões de resposta rápida.	Não
actions	object	Configuração e ações do template em formato de payload.	Não
headerParameters	array	Parâmetro de cabeçalho, máximo 1 parâmetro.	Não
thumbnailProduct	string	URL da imagem em miniatura. Obrigatório para templates de catálogo.	Condicional
expirationTime	string	Tempo de expiração no formato timestamp (milissegundos).	Não
campaignId	string	Identificador único da campanha associada.	Não
buttonParameters	array	Configuração para todos os tipos de botão.	Não
ltoParams	object	Parâmetros de oferta por tempo limitado (LTO).	Não
cards	array	Cartões de conteúdo para templates de carrossel.	Não

Tipos de template

Nesta seção, compartilhamos exemplos de requisição para os diferentes tipos de template. Esses exemplos fornecem um guia claro para que você possa facilmente substituir os valores pelos seus próprios dados.

Se o nome de um template ou um botão dentro do JSON diferir do template já aprovado, mesmo por um acento, o envio falhará. A precisão é fundamental para garantir a funcionalidade.

Mensagem de texto

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "parameters": ["PARAMETER_1", "PARAMETER_2"],
    "destinations": ["PHONE_NUMBER"],
    "elementName": "ELEMENT_NAME"
  }'

Mensagem com imagem

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "parameters": ["PARAMETER_1", "PARAMETER_2"],
    "mediaUrl": "https://cdn.example.com/image.jpeg",
    "type": "image",
    "destinations": ["PHONE_NUMBER"],
    "elementName": "ELEMENT_NAME"
  }'

Mensagem com vídeo

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "parameters": ["PARAMETER_1", "PARAMETER_2"],
    "mediaUrl": "https://cdn.example.com/video.mp4",
    "type": "video",
    "destinations": ["PHONE_NUMBER"],
    "elementName": "ELEMENT_NAME"
  }'

Mensagem com documento anexado

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "parameters": ["PARAMETER_1"],
    "mediaUrl": "https://cdn.example.com/document.pdf",
    "type": "document",
    "destinations": ["PHONE_NUMBER"],
    "elementName": "ELEMENT_NAME"
  }'

Mensagem de texto com botões de ação de URL estática

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "parameters": ["PARAMETER_1"],
    "destinations": ["PHONE_NUMBER"],
    "elementName": "ELEMENT_NAME"
  }'

Mensagem de texto com botões de ação de URL dinâmica

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
  --header 'Accept-Language: en' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "destinations": ["PHONE_NUMBER"],
    "parameters": ["PARAMETER_1"],
    "elementName": "ELEMENT_NAME",
    "buttonParameters": [
      {
        "type": "URL",
        "payload": {"param": "PARAM_URL"}
      }
    ]
  }'

Mensagem de texto com botões de Resposta Rápida

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "elementName": "ELEMENT_NAME",
    "language": "en",
    "type": "text",
    "parameters": ["param1", "param2"],
    "destinations": ["PHONE_NUMBER"],
    "buttonParameters": [
      {
        "type": "QUICK_REPLY",
        "payload": {"type": "edge", "action": "BTN1", "skillId": "1"}
      },
      {
        "type": "QUICK_REPLY",
        "payload": {"type": "edge", "action": "BTN2", "skillId": "2"}
      },
      {
        "type": "QUICK_REPLY",
        "payload": {"type": "edge", "action": "BTN3", "skillId": "3"}
      }
    ]
  }'

Mensagem de texto personalizada com parâmetros de cabeçalho

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "elementName": "ELEMENT_NAME",
    "destinations": ["PHONE_NUMBER"],
    "parameters": ["PARAMETER_1", "PARAMETER_2"],
    "headerParameters": ["PARAMETER_VALUE"]
  }'

Catálogo completo

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "elementName": "ELEMENT_NAME",
    "destinations": ["PHONE_NUMBER"],
    "parameters": ["PARAMETER_1"],
    "type": "catalog",
    "buttonParameters": [
      {
        "type": "CATALOG",
        "payload": {"thumbnailProduct": "productId"}
      }
    ]
  }'

LTO com botão de copiar código

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "buttonOptions": {},
    "elementName": "ELEMENT_NAME",
    "destinations": ["PHONE_NUMBER"],
    "parameters": ["PARAMETER_1", "PARAMETER_2"],
    "type": "image",
    "mediaUrl": "https://cdn.example.com/image.jpeg",
    "ltoParams": {"expirationTime": 1733260800000},
    "buttonParameters": [
      {
        "type": "COPY_CODE",
        "param": 1,
        "payload": {"param": "20OFF"}
      }
    ]
  }'

Autenticação

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "buttonOptions": {},
    "elementName": "ELEMENT_NAME",
    "destinations": ["PHONE_NUMBER"],
    "parameters": ["PARAMETER_1"],
    "type": "hsm"
  }'

Carrossel com 2 cartões

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "elementName": "ELEMENT_NAME",
    "destinations": ["PHONE_NUMBER"],
    "parameters": [],
    "type": "carousel",
    "cards": [
      {
        "mediaUrl": "https://cdn.example.com/product1.jpg",
        "params": ["PARAMETER_VALUE"],
        "buttonParameters": [
          {
            "type": "QUICK_REPLY",
            "payload": {"action": "Button 1", "type": "edge", "skillId": "45515", "cardIndex": 0}
          }
        ]
      },
      {
        "mediaUrl": "https://cdn.example.com/product2.jpg",
        "params": ["PARAMETER_VALUE_1", "PARAMETER_VALUE_2"],
        "buttonParameters": [
          {
            "type": "QUICK_REPLY",
            "payload": {"action": "Button 2", "type": "edge", "skillId": "10192", "cardIndex": 1}
          }
        ]
      }
    ]
  }'

Casos de uso comuns

1. Mensagens personalizadas

Use templates com variáveis para enviar mensagens adaptadas às necessidades de cada usuário (por exemplo, lembretes de pagamento ou atualizações de pedidos).

2. Automação com Webhooks

Interações personalizadas com base nas respostas dos usuários, permitindo uma conversa mais dinâmica e eficiente. Exemplos de campanhas:

Promoções personalizadas: Ofertas exclusivas baseadas nas preferências do cliente.
Lembretes de pagamento: Notificações automáticas para datas de vencimento de faturas.
Cotações de serviço: Consultas rápidas sobre seguros, empréstimos, etc.

Configuração avançada

Número de telefone

Como este é um envio individual, o número de telefone do destinatário deve estar no formato correto para que o envio seja bem-sucedido. O sinal + deve ser omitido, o código do país deve ser incluído e apenas caracteres numéricos são permitidos. Traços ou espaços não são aceitos.

Para usuários no Equador: O sinal ”+” e o primeiro 0 do número de telefone devem ser omitidos para que seja inserido corretamente.

✅ Formato correto	❌ Formato incorreto	❌ Formato incorreto
PHONE_NUMBER	+PHONE_NUMBER	09XXXXXXXX

Parâmetros específicos

Dependendo da campanha, você pode usar dados personalizados como o tipo de mensagem ou informações adicionais do cliente.

Personalização de mensagens

Vinculação com Workflows

Cada mensagem pode ser associada a um fluxo específico que define como a resposta do usuário deve ser tratada. Isso é útil para criar interações mais complexas e direcionadas, como menus interativos ou pesquisas.

Configuração de botões

Button Payload

Você pode usar a seguinte estrutura no campo buttonPayloads quando o seu template incluir botões de resposta rápida usando workflows; isso permitirá que você ative workflows adicionais dentro da conversa com base na ação selecionada pelo usuário.

[
  {"type": "edge", "action": "Yes", "skillId": "1"},
  {"type": "edge", "action": "Reschedule", "skillId": "2"},
  {"type": "edge", "action": "Cancel", "skillId": "3"}
]

Neste caso, cada botão deve ter as chaves type, action e skillId. A chave action define o texto que aparecerá no botão, enquanto skillId indica o ID do fluxo que o botão ativará.

Actions Payload

Redirecione usuários para workflows específicos com base em sua escolha ou interação.Os templates permitem as seguintes configurações:

{
  "actions": {
    "setSkill": {"id": 2222}
  }
}

{
  "actions": {
    "setMemoryParams": {
      "url": "https://apps.jelou.ai"
    }
  }
}

Parâmetros de Cache

Esta função é usada para salvar informações adicionais no cache para uso posterior. Dependerá da configuração desejada para o template. Se uma URL for enviada, ela pode ser usada por um fluxo para redirecionar essa URL para fins de marketing. Todos os parâmetros a serem armazenados em cache devem ir em setMemoryParams com seus respectivos campos chave-valor.

Esta configuração será válida por 3 meses.

{
  "actions": {
    "setMemoryParams": {
      "url": "https://apps.jelou.ai"
    }
  }
}

Respostas da API

200 - Resposta bem-sucedida

[
  {
    "id": "msg-12345-67890-abcde-fghij-klmno",
    "destination": "PHONE_NUMBER"
  }
]

400 - Requisição Inválida

{
  "message": ["Template does not exist"],
  "status": "failed",
  "_metadata": {
    "error": {},
    "body": {
      "destinations": [{"destination": "PHONE_NUMBER"}],
      "parameters": ["John", "example_value"],
      "elementName": "sample_template",
      "code": "en",
      "type": "text",
      "botId": "BOT_ID",
      "botName": "Your Bot"
    }
  },
  "error": {}
}

401 - Não Autorizado

{
  "message": "Authentication failed"
}

404 - Não Encontrado

{
  "message": ["The Bot could not be found at the moment."],
  "statusMessage": "failed",
  "status": 0,
  "error": {
    "code": "E1019",
    "key": "BOT_NOT_FOUND",
    "description": "Error to be thrown when trying to get a Bot.",
    "developerMessages": {
      "es": "El botId no se encuentra en la base de datos o ha sido eliminado.",
      "en": "The botId is not found in the database or has been deleted."
    },
    "clientMessages": {
      "es": "El Bot no se pudo encontrar por el momento.",
      "en": "The Bot could not be found at the moment."
    }
  }
}

422 - Entidade não processável

{
  "message": ["The values entered are not correct."],
  "statusMessage": "failed",
  "status": 0,
  "error": {
    "code": "E0422",
    "key": "VALIDATOR_ERROR",
    "description": "Error to be thrown when cannot process request because of incoming values",
    "developerMessages": {
      "es": "Los valores del request no son correctos para ser procesados.",
      "en": "The request values are not correct for processing."
    },
    "clientMessages": {
      "es": "Los valores ingresados no son correctos.",
      "en": "The values entered are not correct."
    }
  },
  "validationError": {
    "parameters": [
      {
        "en": "The number of parameters is incorrect.",
        "es": "El número de parámetros es incorrecto."
      }
    ]
  }
}

500 - Erro Interno do Servidor

{
  "message": ["We are having trouble processing your request. Please try again later."],
  "statusMessage": "failed",
  "status": 0,
  "error": {
    "code": "E0000",
    "key": "UNKNOWN_ERROR",
    "description": "Error to be thrown when it couldn't be determined the reason of failure",
    "developerMessages": {
      "es": "Error inesperado occurido, revisar logs.",
      "en": "Unexpected error occurred, check logs."
    },
    "clientMessages": {
      "es": "Estamos teniendo problemas procesando la solicitud. Por favor intenta mas tarde.",
      "en": "We are having trouble processing your request. Please try again later."
    }
  }
}

Ferramentas recomendadas para testes

Para facilitar os testes e o envio de requisições, recomendamos o uso de ferramentas como:

Postman
Insomnia

Essas ferramentas permitem que você faça requisições HTTP facilmente, teste diferentes configurações e revise as respostas da API.

Perguntas frequentes

Quantos caracteres são permitidos?

Atualmente não há um limite de caracteres definido por mensagem; no entanto, você deve estar ciente do tamanho dos arquivos que fazem parte da mensagem, como: imagem, vídeo ou documento. Estes são compartilhados via mediaUrl.Na Jelou, temos as seguintes limitações de tamanho e formato a seguir:

DOCUMENT: Até 15MB - Formato: .pdf
VIDEO: Até 15MB - Formato: .mp4
IMAGE: Até 5MB - Formatos: .jpg, .jpeg, .png

Como a API é consumida?

Tanto os cURLs de envio em massa quanto os 1-1 podem ser consumidos em qualquer cliente HTTPS como Insomnia ou Postman. Basta criar uma requisição HTTPS usando o cURL (apenas cole-o), depois altere os dados e execute.Aqui está um exemplo com basic-auth:

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/BOT_ID/hsm' \
  --header 'Accept-Language: en' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "destinations": ["PHONE_NUMBER"],
    "parameters": [],
    "elementName": "your_template_name"
  }'

Autorizações

Authorization

string

header

obrigatório

Basic authentication using Base64 encoded clientId:clientSecret

Parâmetros de caminho

botId

string

obrigatório

The unique identifier of the bot

Corpo

application/json

elementName

string

obrigatório

Approved template name

destinations

string[]

obrigatório

Phone numbers with country code, no + sign

mediaUrl

string<uri>

Public URL for media (required for image/video/document templates)

filename

string

Filename for document templates

type

enum<string>

padrão:text

Opções disponíveis:

text,

hsm,

image,

document,

video,

catalog,

carousel

language

enum<string>

Opções disponíveis:

en,

es,

pt

parameters

string[]

Template parameter values

buttonPayloads

object[]

actions

object

headerParameters

string[]

Maximum array length: 1

buttonParameters

object[]

Show child attributes

ltoParams

object

Show child attributes

cards

object[]

Show child attributes

expirationTime

string

Expiration timestamp in milliseconds

campaignId

string

Resposta

HSM sent successfully

string

destination

string

Criar Template

Envio em Massa

⌘I

Documentation Index

​Configuração do envio de mensagens

​Passo 1: Definir o Endpoint

​Passo 2: Parâmetros da Requisição

​Passo 3: Enviar a requisição

​Restrições de conteúdo

​Corpo da Requisição

​Tipos de template

​Casos de uso comuns

​1. Mensagens personalizadas

​2. Automação com Webhooks

​Configuração avançada

​Número de telefone

​Parâmetros específicos

​Personalização de mensagens

​Vinculação com Workflows

​Configuração de botões

​Parâmetros de Cache

​Respostas da API

​Ferramentas recomendadas para testes

​Perguntas frequentes

Autorizações

Parâmetros de caminho

Corpo

Resposta

Configuração do envio de mensagens

Passo 1: Definir o Endpoint

Passo 2: Parâmetros da Requisição

Passo 3: Enviar a requisição

Restrições de conteúdo

Corpo da Requisição

Tipos de template

Casos de uso comuns

1. Mensagens personalizadas

2. Automação com Webhooks

Configuração avançada

Número de telefone

Parâmetros específicos

Personalização de mensagens

Vinculação com Workflows

Configuração de botões

Parâmetros de Cache

Respostas da API

Ferramentas recomendadas para testes

Perguntas frequentes