Envio em Massa

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 o identificador de cada destinatário: um número de telefone ou um BSUID. Para números de telefone, é obrigatório incluir o código internacional sem o símbolo + (por exemplo, para um número no Equador, escreva PHONE_NUMBER).

Não é possível usar BSUID para enviar plantillas da categoria AUTHENTICATION (OTP); esse destinatário deve ser enviado como número de telefone. Se uma linha com BSUID apontar para uma plantilla AUTHENTICATION, essa linha é omitida do envio sem afetar o restante do arquivo.

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 canal 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: `hsm` (somente texto), `image`, `video`, `document` ou `carousel`. Se omitido, é enviado como template de texto.	Não
language	string	Código de idioma do template, por exemplo `es`, `en` ou `pt_BR`.	Não
mediaUrl	string	URL pública do arquivo de mídia do cabeçalho. 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
headerParameters	array	Parâmetro variável do cabeçalho de texto, obtido de uma coluna do CSV. Máximo de 1 parâmetro.	Não
buttonParameters	array	Configuração dos botões do template: resposta rápida (`QUICK_REPLY`) ou URL dinâmica (`URL`).	Não
cards	array	Cards do carrossel. Obrigatório quando `type` é `carousel`.	Condicional
actions	object	Ações executadas quando o destinatário responde: workflow de destino, memória e CRM.	Não
date	string	Data e hora em UTC (ISO 8601) em que a campanha será enviada. Se omitido, a campanha é enviada imediatamente.	Não

Exemplos de requisição

Por método de envio do arquivo

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",
    "buttonParameters": [
      {"type": "QUICK_REPLY", "payload": {"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 'buttonParameters=[{"type":"QUICK_REPLY","payload":{"type":"edge","action":"Yes","skillId":"1"}},{"type":"QUICK_REPLY","payload":{"type":"edge","action":"Reschedule","skillId":"2"}},{"type":"QUICK_REPLY","payload":{"type":"edge","action":"Cancel","skillId":"3"}}]' \
  --form file=@/local/path/campaign.csv \
  --form 'params=[]'

Por tipo de template

Cada exemplo usa um arquivo CSV publicado em fileUrl cujas colunas correspondem às indicadas em params.

Texto

Template: Olá {{1}}, seu pedido {{2}} já está a caminho.

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignName": "pedidos_a_caminho",
    "botId": "BOT_ID",
    "elementName": "pedido_a_caminho",
    "language": "pt_BR",
    "type": "hsm",
    "params": [
      {"param": 1, "column": "nome"},
      {"param": 2, "column": "numero_pedido"}
    ],
    "fileUrl": "https://cdn.example.com/campanhas/pedidos.csv"
  }'

Imagem

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignName": "promo_fim_de_mes",
    "botId": "BOT_ID",
    "elementName": "promo_fim_de_mes",
    "language": "pt_BR",
    "type": "image",
    "params": [
      {"param": 1, "column": "nome"}
    ],
    "mediaUrl": "https://cdn.example.com/media/promo-fim-de-mes.jpg",
    "fileUrl": "https://cdn.example.com/campanhas/clientes-promo.csv"
  }'

Vídeo

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignName": "lancamento_app",
    "botId": "BOT_ID",
    "elementName": "lancamento_app_video",
    "language": "pt_BR",
    "type": "video",
    "params": [],
    "mediaUrl": "https://cdn.example.com/media/lancamento-app.mp4",
    "fileUrl": "https://cdn.example.com/campanhas/usuarios-app.csv"
  }'

Documento

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignName": "extrato_setembro",
    "botId": "BOT_ID",
    "elementName": "extrato_conta",
    "language": "pt_BR",
    "type": "document",
    "params": [
      {"param": 1, "column": "nome"},
      {"param": 2, "column": "produto"}
    ],
    "mediaUrl": "https://cdn.example.com/media/extrato-conta.pdf",
    "fileUrl": "https://cdn.example.com/campanhas/extratos.csv"
  }'

Carrossel

Cada card define seu próprio recurso de mídia em mediaUrl e seus botões em buttonParameters. O campo cardIndex indica a qual card cada botão pertence, começando em 0.

curl --request POST \
  --url https://api.jelou.ai/v1/hsm/file \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignName": "catalogo_temporada",
    "botId": "BOT_ID",
    "elementName": "catalogo_temporada",
    "language": "pt_BR",
    "type": "carousel",
    "params": [],
    "fileUrl": "https://cdn.example.com/campanhas/clientes-catalogo.csv",
    "cards": [
      {
        "mediaUrl": "https://cdn.example.com/media/produto-1.jpg",
        "params": [],
        "buttonParameters": [
          {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Ver produto 1", "skillId": "1", "cardIndex": 0}}
        ]
      },
      {
        "mediaUrl": "https://cdn.example.com/media/produto-2.jpg",
        "params": [],
        "buttonParameters": [
          {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Ver produto 2", "skillId": "2", "cardIndex": 1}}
        ]
      },
      {
        "mediaUrl": "https://cdn.example.com/media/produto-3.jpg",
        "params": [],
        "buttonParameters": [
          {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Ver produto 3", "skillId": "3", "cardIndex": 2}}
        ]
      }
    ]
  }'

Por cenário

Estes exemplos mostram o corpo JSON da requisição. Envie-o ao mesmo endpoint com o cabeçalho Content-Type: application/json.

Botões de resposta rápida que ativam um workflow

Cada botão com payload.type igual a edge leva o destinatário ao workflow indicado em skillId. O texto de action deve corresponder ao texto do botão no template.

{
  "campaignName": "confirmacao_consultas",
  "botId": "BOT_ID",
  "elementName": "confirmar_consulta",
  "language": "pt_BR",
  "type": "hsm",
  "params": [
    {"param": 1, "column": "nome"},
    {"param": 2, "column": "data_consulta"}
  ],
  "fileUrl": "https://cdn.example.com/campanhas/consultas.csv",
  "buttonParameters": [
    {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Confirmar", "skillId": "1"}},
    {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Reagendar", "skillId": "2"}},
    {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Cancelar", "skillId": "3"}}
  ]
}

Botão de URL dinâmica

O sufixo da URL é obtido da coluna do CSV indicada em payload.param. Por exemplo, se o template define a URL https://solicitacoes.example.com/{{1}}, cada destinatário recebe seu próprio link.

{
  "campaignName": "acompanhamento_solicitacoes",
  "botId": "BOT_ID",
  "elementName": "acompanhamento_solicitacao",
  "language": "pt_BR",
  "type": "hsm",
  "params": [
    {"param": 1, "column": "nome"},
    {"param": 2, "column": "numero_solicitacao"}
  ],
  "fileUrl": "https://cdn.example.com/campanhas/solicitacoes.csv",
  "buttonParameters": [
    {"type": "URL", "param": 1, "payload": {"param": "url_solicitacao"}}
  ]
}

Parâmetro no cabeçalho

Para templates com uma variável no cabeçalho de texto, indique a coluna do CSV em headerParameters.

{
  "campaignName": "boas_vindas_clientes",
  "botId": "BOT_ID",
  "elementName": "boas_vindas_personalizada",
  "language": "pt_BR",
  "type": "hsm",
  "headerParameters": [
    {"param": "1", "column": "nome"}
  ],
  "params": [
    {"param": 1, "column": "codigo_cliente"}
  ],
  "fileUrl": "https://cdn.example.com/campanhas/novos-clientes.csv"
}

Direcionar a resposta para um workflow

Com actions.setSkill, a resposta do destinatário é direcionada ao workflow indicado.

{
  "campaignName": "lembrete_pagamento",
  "botId": "BOT_ID",
  "elementName": "lembrete_pagamento",
  "language": "pt_BR",
  "type": "hsm",
  "params": [
    {"param": 1, "column": "nome"},
    {"param": 2, "column": "valor"},
    {"param": 3, "column": "data_vencimento"}
  ],
  "fileUrl": "https://cdn.example.com/campanhas/pagamentos-pendentes.csv",
  "actions": {
    "setSkill": {"id": 5001}
  }
}

Salvar dados do CSV na memória e no CRM

Use {nome_coluna} como valor para obter o dado dessa coluna do CSV. setMemoryParams salva os valores na memória do usuário, e crmParams os salva nos campos do CRM.

{
  "campaignName": "renovacao_seguros",
  "botId": "BOT_ID",
  "elementName": "renovacao_apolice",
  "language": "pt_BR",
  "type": "hsm",
  "params": [
    {"param": 1, "column": "nome"},
    {"param": 2, "column": "produto"}
  ],
  "fileUrl": "https://cdn.example.com/campanhas/renovacoes.csv",
  "actions": {
    "setMemoryParams": {
      "nome_cliente": "{nome}",
      "produto": "{produto}"
    },
    "crmParams": {
      "nome": "{nome}",
      "cidade": "{cidade}"
    }
  }
}

Envio agendado

Com date, você agenda a campanha para uma data e hora em UTC.

{
  "campaignName": "black_friday",
  "botId": "BOT_ID",
  "elementName": "black_friday_2026",
  "language": "pt_BR",
  "type": "image",
  "params": [
    {"param": 1, "column": "nome"}
  ],
  "mediaUrl": "https://cdn.example.com/media/black-friday.jpg",
  "fileUrl": "https://cdn.example.com/campanhas/clientes-black-friday.csv",
  "date": "2026-11-27T14:00:00Z"
}

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.

headerParameters usa a mesma estrutura, mas aceita apenas um elemento.

Estrutura de buttonParameters

Cada elemento do array configura um botão do template. Resposta rápida (QUICK_REPLY):

[
  {"type": "QUICK_REPLY", "payload": {"type": "edge", "action": "Confirmar", "skillId": "1"}},
  {"type": "QUICK_REPLY", "payload": {"type": "flow", "action": "Ver oferta", "flowId": "2"}}
]

payload.type: Destino do botão. edge ativa um workflow e flow ativa um flow.
payload.action: Texto do botão. Deve corresponder ao texto definido no template.
payload.skillId: ID do workflow ativado. Obrigatório quando payload.type é edge.
payload.flowId: ID do flow ativado. Obrigatório quando payload.type é flow.
payload.cardIndex: Posição do card ao qual o botão pertence, começando em 0. Somente para carrosséis.

Para obter o skillId de um workflow, passe o cursor sobre o nome do workflow no Brain Studio. Um tooltip será exibido com o ID correspondente.

URL dinâmica (URL):

[
  {"type": "URL", "param": 1, "payload": {"param": "url_solicitacao"}}
]

param: Número do parâmetro da URL no template.
payload.param: Coluna do CSV com o valor que completa a URL.

Estrutura de cards

Cada card do carrossel é um objeto com:

mediaUrl: URL pública da imagem ou do vídeo do card.
params: Parâmetros do corpo do card, com a mesma estrutura de params. Use um array vazio se o card não tiver parâmetros.
buttonParameters: Botões do card. Cada payload deve incluir cardIndex.

Estrutura de actions

Propriedade	Descrição	Exemplo
setSkill	Workflow que atende a resposta do destinatário.	`{"id": 1}`
setMemoryParams	Valores salvos na memória do usuário. Use `{coluna}` para obter o valor do CSV.	`{"produto": "{produto}"}`
crmParams	Valores salvos nos campos do CRM. Use `{coluna}` para obter o valor do CSV.	`{"cidade": "{cidade}"}`

Referência de API

Enviar Mensagens

Campanhas

Conversações

Etiquetas

Métricas

Usuários

Recursos

Widget

Datum

Painel de Atendimento Externo

Canal Personalizado

Gestão de Memória

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

Por método de envio do arquivo

Por tipo de template

Por cenário

Respostas do envio

Estrutura de params

Estrutura de buttonParameters

Estrutura de cards

Estrutura de actions

​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

​Por método de envio do arquivo

​Por tipo de template

​Por cenário

​Respostas do envio

​Estrutura de params

​Estrutura de buttonParameters

​Estrutura de cards

​Estrutura de actions

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

Por método de envio do arquivo

Por tipo de template

Por cenário

Respostas do envio

Estrutura de params

Estrutura de buttonParameters

Estrutura de cards

Estrutura de actions