Envio em Massa - Jelou AI Docs

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>"
}

POST

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_number	param_1	param_2	param_3
PHONE_NUMBER	A12345	$250.00	December 1
PHONE_NUMBER_2	B67890	$100.50	December 2
PHONE_NUMBER_3	C22345	$50.00	December 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:

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.
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

Propriedade	Tipo	Descrição	Obrigatório
campaignName	string	Nome atribuído à campanha sendo enviada.	Sim
elementName	string	Nome do template. Deve ter status aprovado pelo WhatsApp.	Sim
botId	string	Identificador único do bot que envia o template.	Sim
params	array	Array 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
type	string	Tipo de template: `text`, `image`, `document`, `video`. Padrão é `text`.	Não
mediaUrl	string	URL pública do arquivo de mídia. Obrigatório para templates de imagem, vídeo ou documento.	Condicional
fileUrl	string	URL pública do arquivo CSV. Obrigatório se o arquivo não for enviado diretamente.	Condicional
file	file	Arquivo CSV anexado. Obrigatório se `fileUrl` não for usado.	Condicional
buttonPayloads	array	Array de objetos para botões de resposta rápida com workflows.	Não
actions	object	Ações relacionadas ao template.	Não
scheduledAt	date	Data e hora em UTC quando a campanha será enviada.	Não

Exemplos de requisição

Enviar a partir de URL pública (JSON)

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"}
    ]
  }'

Enviar com arquivo anexado (multipart/form-data)

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

200 - Resposta bem-sucedida

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

400 - Requisição Inválida

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

401 - Não Autorizado

{
  "message": "Authentication failed"
}

422 - Entidade não processável

{
  "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 workflows:

[
  {"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

Show child attributes

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

Envio Individual (1-1)

Notificações

⌘I

Documentation Index

​Diretrizes do template

​Formato do arquivo

​Cabeçalho

​Primeira coluna

​Colunas restantes

​Exemplo

​Enviar HSM a partir de arquivo

​Opções de upload de arquivo

​Parâmetros do corpo

​Exemplos de requisição

​Respostas do envio

​Estrutura de params

​Estrutura de buttonPayloads

Autorizações

Corpo

Resposta

Diretrizes do template

Formato do arquivo

Cabeçalho

Primeira coluna

Colunas restantes

Exemplo

Enviar HSM a partir de arquivo

Opções de upload de arquivo

Parâmetros do corpo

Exemplos de requisição

Respostas do envio

Estrutura de params

Estrutura de buttonPayloads