Envie mensagens com facilidade

A API ZionTalk permite enviar mensagens de texto e arquivos de forma programática. Integre em minutos e comece a se comunicar com seus clientes.

Primeiros Passos

Siga estes 3 passos simples para enviar sua primeira mensagem:

Obtenha sua API Key

Acesse o ZionTalk, vá até a lista de canais e clique para editar o canal que será usado para disparar as mensagens. No campo API Key, clique no botão para gerar uma nova chave, copie e salve.

Configure a Autenticação

Use Basic Auth com sua API Key como username e uma senha vazia. O header de autenticação será gerado automaticamente pelo seu cliente HTTP.

Username sua_api_key

Password (vazio)

Envie sua Primeira Mensagem

Faça uma requisição POST para o endpoint com os dados da mensagem. Veja o exemplo abaixo:

Exemplo Rápido

curl -X POST 'https://app.ziontalk.com/api/send_message/' \
  -u 'sua_api_key:' \
  -F 'msg=Olá! Esta é minha primeira mensagem.' \
  -F 'mobile_phone=+5511999999999'

Autenticação

A API utiliza Basic Authentication. Você deve enviar suas credenciais em todas as requisições.

Como funciona

A maioria das bibliotecas HTTP e ferramentas como cURL geram automaticamente o header Authorization quando você fornece username e password.

Username sua_api_key

Password (string vazia)

Tipo Basic Auth

Enviar Mensagem

Utilize este endpoint para enviar mensagens de texto e arquivos para seus destinatários.

POST https://app.ziontalk.com/api/send_message/

Envia uma mensagem de texto e/ou arquivos para o número de telefone especificado.

Content-Type

As requisições aceitam multipart/form-data ou application/x-www-form-urlencoded. Se houver anexos, é obrigatório usar multipart/form-data.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
msg	string	Sim	A mensagem de texto que será enviada ao destinatário.
mobile_phone	string	Sim	Número do destinatário. Ex: `+5511999999999` ou `11999999999` (usando `cd`).
cd	string	Não	Código do país como prefixo. Ex: `+55`, `+54`. Opcional se o número já estiver no formato internacional (E.164).
attachments	file	Não	Arquivo(s) a serem enviados como anexo. Você pode enviar múltiplos arquivos.

Formato do número

Você pode enviar o número completo no formato E.164 (ex: +5511999999999) ou usar o parâmetro cd para definir o código do país separadamente.

Exemplo de Requisição

# Enviar mensagem de texto
curl -X POST 'https://app.ziontalk.com/api/send_message/' \
  -u 'sua_api_key:' \
  -F 'msg=Olá! Como posso ajudar?' \
  -F 'mobile_phone=+5511999999999'

# pip install requests
import requests

url = "https://app.ziontalk.com/api/send_message/"

data = {
    "msg": "Olá! Como posso ajudar?",
    "mobile_phone": "+5511999999999"
}

response = requests.post(
    url,
    data=data,
    auth=("sua_api_key", "")
)

print(response.status_code)

// Usando fetch
const formData = new FormData();
formData.append('msg', 'Olá! Como posso ajudar?');
formData.append('mobile_phone', '+5511999999999');

const response = await fetch(
  'https://app.ziontalk.com/api/send_message/',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Basic ' + btoa('sua_api_key:')
    },
    body: formData
  }
);

console.log(response.status);

<?php

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => "https://app.ziontalk.com/api/send_message/",
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => "sua_api_key:",
    CURLOPT_POSTFIELDS => [
        "msg" => "Olá! Como posso ajudar?",
        "mobile_phone" => "+5511999999999"
    ]
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $httpCode;

Exemplo com Anexos

# Enviar mensagem com arquivos anexos
curl -X POST 'https://app.ziontalk.com/api/send_message/' \
  -u 'sua_api_key:' \
  -F 'msg=Segue os documentos.' \
  -F 'mobile_phone=+5511999999999' \
  -F 'attachments=@/caminho/para/documento.pdf' \
  -F 'attachments=@/caminho/para/imagem.jpg'

# pip install requests
import requests

url = "https://app.ziontalk.com/api/send_message/"

data = {
    "msg": "Segue os documentos.",
    "mobile_phone": "+5511999999999"
}

files = [
    ("attachments", open("documento.pdf", "rb")),
    ("attachments", open("imagem.jpg", "rb"))
]

response = requests.post(
    url,
    data=data,
    files=files,
    auth=("sua_api_key", "")
)

print(response.status_code)

// Usando fetch com arquivos
const formData = new FormData();
formData.append('msg', 'Segue os documentos.');
formData.append('mobile_phone', '+5511999999999');

// Adicionar arquivos
const fileInput = document.querySelector('input[type="file"]');
for (const file of fileInput.files) {
  formData.append('attachments', file);
}

const response = await fetch(
  'https://app.ziontalk.com/api/send_message/',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Basic ' + btoa('sua_api_key:')
    },
    body: formData
  }
);

console.log(response.status);

<?php

$ch = curl_init();

$postFields = [
    "msg" => "Segue os documentos.",
    "mobile_phone" => "+5511999999999",
    "attachments[0]" => new CURLFile("/caminho/documento.pdf"),
    "attachments[1]" => new CURLFile("/caminho/imagem.jpg")
];

curl_setopt_array($ch, [
    CURLOPT_URL => "https://app.ziontalk.com/api/send_message/",
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => "sua_api_key:",
    CURLOPT_POSTFIELDS => $postFields
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $httpCode;

Enviar Template

Utilize este endpoint para enviar mensagens baseadas em templates aprovados no painel da Meta através da API Oficial do WhatsApp Business.

API Oficial do WhatsApp

Este endpoint utiliza a API oficial da Meta. Os templates devem estar previamente aprovados no Gerenciador de Negócios da Meta antes de serem utilizados.

POST https://app.ziontalk.com/api/send_template_message/

Envia uma mensagem utilizando um template pré-aprovado pela Meta, com suporte a parâmetros dinâmicos no cabeçalho e corpo.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
mobile_phone	string	Sim	Número do destinatário. Ex: `+5511999999999` ou `11999999999` (usando `cd`).
cd	string	Não	Código do país como prefixo. Ex: `+55`, `+54`. Opcional se o número já estiver no formato internacional (E.164).
template_identifier	string	Sim	Nome do template cadastrado no painel da Meta. Ex: `voce_esta_perdendo_vendas_no_whatsapp`
language	string	Não	Código do idioma do template. Ex: `pt_BR`, `es`. Se não informado, usa o valor padrão configurado.
headerParams[{nome}]	string	Não	Parâmetros dinâmicos do cabeçalho do template. Substitua `{nome}` pelo nome da variável.
bodyParams[{nome}]	string	Não	Parâmetros dinâmicos do corpo do template. Substitua `{nome}` pelo nome da variável.

Identificando o template

O template é identificado pela combinação de template_identifier + language. Certifique-se de que o template está aprovado no painel da Meta antes de utilizá-lo.

Exemplo de Requisição

# Enviar template com parâmetros
curl -X POST 'https://app.ziontalk.com/api/send_template_message/' \
  -u 'sua_api_key:' \
  -F 'mobile_phone=+5511999999999' \
  -F 'template_identifier=voce_esta_perdendo_vendas_no_whatsapp' \
  -F 'language=pt_BR' \
  -F 'headerParams[nome_empresa]=Minha Loja' \
  -F 'bodyParams[nome_cliente]=João' \
  -F 'bodyParams[desconto]=20%'

# pip install requests
import requests

url = "https://app.ziontalk.com/api/send_template_message/"

data = {
    "mobile_phone": "+5511999999999",
    "template_identifier": "voce_esta_perdendo_vendas_no_whatsapp",
    "language": "pt_BR",
    "headerParams[nome_empresa]": "Minha Loja",
    "bodyParams[nome_cliente]": "João",
    "bodyParams[desconto]": "20%"
}

response = requests.post(
    url,
    data=data,
    auth=("sua_api_key", "")
)

print(response.json())

// Usando fetch
const formData = new FormData();
formData.append('mobile_phone', '+5511999999999');
formData.append('template_identifier', 'voce_esta_perdendo_vendas_no_whatsapp');
formData.append('language', 'pt_BR');
formData.append('headerParams[nome_empresa]', 'Minha Loja');
formData.append('bodyParams[nome_cliente]', 'João');
formData.append('bodyParams[desconto]', '20%');

const response = await fetch(
  'https://app.ziontalk.com/api/send_template_message/',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Basic ' + btoa('sua_api_key:')
    },
    body: formData
  }
);

const data = await response.json();
console.log(data);

Respostas da API

Veja abaixo o formato de resposta da API.

201 Created Mensagem enviada com sucesso

# Resposta sem corpo, apenas o status HTTP 201

Tratamento de Erros

Quando ocorre um erro, a API retorna uma string de texto simples descrevendo o problema.

Importante

Sempre verifique o código de status HTTP da resposta. Se for diferente de 201, trate o corpo da resposta como texto simples, não como JSON.

Suporte

Precisa de ajuda com a integração? Nossa equipe está pronta para auxiliar você.

Entre em contato

Para tirar dúvidas técnicas sobre a integração, entre em contato com nossa equipe de suporte.