Pular para o conteúdo principal
POST
/
v1
/
hsm
/
file
Send Bulk HSM
curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "campaignName": "<string>",
  "elementName": "<string>",
  "botId": "<string>",
  "params": [
    {
      "param": 123,
      "column": "<string>"
    }
  ],
  "type": "text",
  "mediaUrl": "<string>",
  "fileUrl": "<string>",
  "buttonPayloads": [
    {}
  ],
  "actions": {},
  "scheduledAt": "2023-11-07T05:31:56Z"
}
'
{
  "message": [
    "<string>"
  ],
  "status": "<string>"
}
Use esta função para enviar templates em massa para seus clientes. A API cuidará da entrega aos destinatários a partir de um arquivo baseado em colunas. O envio de templates em massa permite que você envie um template predefinido com valores diferentes relacionados a cada cliente, para que você possa selecionar informações dinâmicas de uma fonte como um arquivo, para automatizar e enviar sua campanha facilmente.

​
Diretrizes do template

O arquivo de origem deve ser criado seguindo estas especificações:

​
Formato do arquivo

Apenas arquivos com a extensão .CSV são suportados.

​
Cabeçalho

A primeira linha do arquivo deve definir os nomes das colunas (cabeçalho). Siga estas regras para o cabeçalho:
  • Evite espaços em branco nos nomes das colunas.
  • Não use caracteres especiais ou marcas de pontuação (ex.: !, $, %, &, *, etc.).
  • Use apenas letras, números e underscores (_) se necessário.
Correto: phone_number, customer_name, order_amount Incorreto: phone number, customer-name!, order#amount

​
Primeira coluna

A primeira coluna deve conter os números de telefone dos destinatários. É obrigatório incluir o código internacional sem o símbolo + (por exemplo, para um número no Equador, escreva PHONE_NUMBER).

​
Colunas restantes

As outras colunas serão usadas para os valores dinâmicos dos parâmetros (personalização do template).

​
Exemplo

Se o seu template contém o seguinte conteúdo: 
Your order {{1}} for a total of {{2}} is confirmed. The expected delivery is {{3}}.
O arquivo CSV seria:
phone_numberparam_1param_2param_3
PHONE_NUMBERA12345$250.00December 1
PHONE_NUMBER_2B67890$100.50December 2
PHONE_NUMBER_3C22345$50.00December 3
O arquivo CSV deve ser codificado em UTF-8.

​
Enviar HSM a partir de arquivo

POST https://api.jelou.ai/v1/hsm/file

​
Opções de upload de arquivo

Há duas formas de fornecer o arquivo CSV com informações dos destinatários:
  1. Usando uma URL pública: Você pode fornecer a URL para o arquivo CSV que está disponível publicamente. Neste caso, o corpo da requisição deve estar no formato JSON.
  2. Fazendo upload do arquivo: Alternativamente, você pode anexar o arquivo CSV diretamente à requisição. Neste caso, o corpo da requisição deve estar no formato multipart/form-data.

​
Parâmetros do corpo

PropriedadeTipoDescriçãoObrigatório
campaignNamestringNome atribuído à campanha sendo enviada.Sim
elementNamestringNome do template. Deve ter status aprovado pelo WhatsApp.Sim
botIdstringIdentificador único do bot que envia o template.Sim
paramsarrayArray de objetos com o número do parâmetro e a coluna CSV correspondente. Se o template não tiver parâmetros, o array deve estar vazio.Sim
typestringTipo de template: text, image, document, video. Padrão é text.Não
mediaUrlstringURL pública do arquivo de mídia. Obrigatório para templates de imagem, vídeo ou documento.Condicional
fileUrlstringURL pública do arquivo CSV. Obrigatório se o arquivo não for enviado diretamente.Condicional
filefileArquivo CSV anexado. Obrigatório se fileUrl não for usado.Condicional
buttonPayloadsarrayArray de objetos para botões de resposta rápida com skills.Não
actionsobjectAções relacionadas ao template.Não
scheduledAtdateData e hora em UTC quando a campanha será enviada.Não

​
Exemplos de requisição

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignName": "campaign_name",
    "botId": "BOT_ID",
    "elementName": "ELEMENT_NAME",
    "params": [
      {"param": 1, "column": "customer_name"}
    ],
    "mediaUrl": "https://cdn.example.com/image.png",
    "type": "image",
    "fileUrl": "https://cdn.example.com/campaign.csv",
    "buttonPayloads": [
      {"type": "edge", "action": "Yes", "skillId": "1"}
    ]
  }'

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --form campaignName=campaign_name \
  --form botId=BOT_ID \
  --form elementName=ELEMENT_NAME \
  --form 'buttonPayloads=[{"type":"edge","action":"Yes","skillId":"1"},{"type":"edge","action":"Reschedule","skillId":"2"},{"type":"edge","action":"Cancel","skillId":"3"}]' \
  --form file=@/local/path/campaign.csv \
  --form 'params=[]'

​
Respostas do envio

{
  "message": ["Campaign has been created."],
  "status": "success"
}

{
  "message": ["Invalid CSV format"],
  "status": "failed"
}

{
  "message": "Authentication failed"
}

{
  "message": ["Template not found or not approved"],
  "status": "failed"
}

​
Estrutura de params

Cada elemento no array params é um objeto que contém: 
[
  {"param": 1, "column": "customer_name"},
  {"param": 2, "column": "order_amount"}
]
  • param: Número do parâmetro no template (1, 2, 3…).
  • column: Nome da coluna no arquivo CSV da qual os valores serão extraídos.

​
Estrutura de buttonPayloads

Para templates com botões de resposta rápida que ativam skills: 
[
  {"type": "edge", "action": "Yes", "skillId": "1"},
  {"type": "edge", "action": "Reschedule", "skillId": "2"},
  {"type": "edge", "action": "Cancel", "skillId": "3"}
]

Autorizações

​
Authorization
string
header
obrigatório

Basic authentication using Base64 encoded clientId:clientSecret

Corpo

​
campaignName
string
obrigatório
​
elementName
string
obrigatório
​
botId
string
obrigatório
​
params
object[]
obrigatório
​
type
enum<string>
padrão:text
Opções disponíveis:
text,
image,
document,
video
​
mediaUrl
string<uri>
​
fileUrl
string<uri>
​
buttonPayloads
object[]
​
actions
object
​
scheduledAt
string<date-time>

Resposta

Campaign created successfully

​
message
string[]
​
status
string