Documentação da API

curl -X POST https://api.zivlo.com.br/v1/messages/send \
  -H "Authorization: Bearer whsp_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "uuid-da-conta",
    "messaging_product": "whatsapp",
    "to": "5511999998888",
    "type": "text",
    "text": { "body": "Olá! Sua consulta foi confirmada." }
  }'

curl -X POST https://api.zivlo.com.br/v1/messages/send \
  -H "Authorization: Bearer whsp_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "uuid-da-conta",
    "messaging_product": "whatsapp",
    "to": "5511999998888",
    "type": "image",
    "image": {
      "link": "https://exemplo.com/imagem.jpg",
      "caption": "Veja nossa novidade!"
    }
  }'

curl -X POST https://api.zivlo.com.br/v1/messages/send \
  -H "Authorization: Bearer whsp_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "uuid-da-conta",
    "messaging_product": "whatsapp",
    "to": "5511999998888",
    "type": "template",
    "template": {
      "name": "confirmacao_consulta",
      "language": { "code": "pt_BR" },
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "João Silva" },
            { "type": "text", "text": "20/03/2026 às 14h" }
          ]
        }
      ]
    }
  }'

const response = await fetch('https://api.zivlo.com.br/v1/messages/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer whsp_sua_chave',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    account_id: 'uuid-da-conta',
    messaging_product: 'whatsapp',
    to: '5511999998888',
    type: 'text',
    text: { body: 'Olá! Sua consulta foi confirmada.' },
  }),
});

const data = await response.json();
console.log(data); // { ok: true, wa_message_id: "wamid.xxx" }

import requests

url = "https://api.zivlo.com.br/v1/messages/send"

headers = {
    "Authorization": "Bearer whsp_sua_chave",
    "Content-Type": "application/json",
}

payload = {
    "account_id": "uuid-da-conta",
    "messaging_product": "whatsapp",
    "to": "5511999998888",
    "type": "text",
    "text": {"body": "Olá! Sua consulta foi confirmada."},
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())  # {'ok': True, 'wa_message_id': 'wamid.xxx'}

// Baileys
{ "ok": true }

// Cloud API
{
  "ok": true,
  "wa_message_id": "wamid.HBgNNTUxMTk5OTk5ODg4FQIAERgSM..."
}

curl -X POST https://api.zivlo.com.br/v1/flows/trigger \
  -H "Authorization: Bearer whsp_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "uuid-da-conta",
    "flow_id": "uuid-do-fluxo",
    "to": "5511999998888"
  }'

curl -X POST https://api.zivlo.com.br/v1/flows/trigger \
  -H "Authorization: Bearer whsp_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "uuid-da-conta",
    "flow_id": "uuid-do-fluxo",
    "to": "5511999998888",
    "variables": {
      "nome_paciente": "João Silva",
      "data_consulta": "20/03/2026",
      "horario": "14h30",
      "medico": "Dr. Carlos"
    }
  }'

curl -X POST https://api.zivlo.com.br/v1/flows/trigger \
  -H "Authorization: Bearer whsp_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "uuid-da-conta",
    "flow_id": "uuid-do-fluxo",
    "to": "5511999998888",
    "force": true
  }'

// Disparar fluxo com variáveis de agendamento
async function triggerAppointmentFlow(phone, appointment) {
  const response = await fetch('https://api.zivlo.com.br/v1/flows/trigger', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ZIVLO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      account_id: process.env.ZIVLO_ACCOUNT_ID,
      flow_id: 'uuid-do-fluxo-consulta',
      to: phone,
      variables: {
        nome_paciente: appointment.patientName,
        data_consulta: appointment.date,
        horario: appointment.time,
        medico: appointment.doctor,
      },
    }),
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(err.error);
  }

  return await response.json();
  // { ok: true, session_id: "uuid-da-sessao" }
}

// Uso com webhook de agendamento
app.post('/webhook/agendamento', async (req, res) => {
  const { phone, ...appointment } = req.body;
  try {
    const result = await triggerAppointmentFlow(phone, appointment);
    res.json({ success: true, session_id: result.session_id });
  } catch (e) {
    res.status(500).json({ error: e.message });
  }
});

import requests
import os

def trigger_flow(phone: str, flow_id: str, variables: dict = None, force: bool = False):
    """Dispara um fluxo Zivlo para um número de WhatsApp."""
    url = "https://api.zivlo.com.br/v1/flows/trigger"

    headers = {
        "Authorization": f"Bearer {os.environ['ZIVLO_API_KEY']}",
        "Content-Type": "application/json",
    }

    payload = {
        "account_id": os.environ["ZIVLO_ACCOUNT_ID"],
        "flow_id": flow_id,
        "to": phone,
        "force": force,
    }

    if variables:
        payload["variables"] = variables

    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()
    return response.json()


# Exemplo: Notificar paciente de consulta
result = trigger_flow(
    phone="5511999998888",
    flow_id="uuid-fluxo-consulta",
    variables={
        "nome_paciente": "João Silva",
        "data_consulta": "20/03/2026",
        "horario": "14h30",
    }
)
print(result)  # {'ok': True, 'session_id': 'uuid-da-sessao'}

{
  "ok": true,
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

curl -X POST https://api.zivlo.com.br/v1/contacts/lists \
  -H "Authorization: Bearer whsp_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clientes Black Friday",
    "description": "Campanha de novembro 2026"
  }'

const res = await fetch('https://api.zivlo.com.br/v1/contacts/lists', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ZIVLO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Clientes Black Friday',
    description: 'Campanha de novembro 2026',
  }),
});

const { list, created } = await res.json();
console.log('List ID:', list.id, '(new:', created, ')');

import os, requests

res = requests.post(
    "https://api.zivlo.com.br/v1/contacts/lists",
    headers={
        "Authorization": f"Bearer {os.environ['ZIVLO_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "name": "Clientes Black Friday",
        "description": "Campanha de novembro 2026",
    },
)
res.raise_for_status()
list_id = res.json()["list"]["id"]
print("List ID:", list_id)

{
  "ok": true,
  "created": true,
  "list": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Clientes Black Friday",
    "description": "Campanha de novembro 2026",
    "contact_count": 0,
    "created_at": "2026-04-24T12:34:56Z"
  }
}

curl -X POST https://api.zivlo.com.br/v1/contacts/import \
  -H "Authorization: Bearer whsp_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "list_name": "Clientes Black Friday",
    "contacts": [
      { "phone": "+55 11 99999-8888", "name": "João Silva", "email": "joao@example.com" },
      { "phone": "5511999997777", "name": "Maria Souza", "tags": ["vip", "whatsapp-ads"] }
    ]
  }'

curl -X POST https://api.zivlo.com.br/v1/contacts/import \
  -H "Authorization: Bearer whsp_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "list_id": "uuid-da-lista",
    "upsert": false,
    "contacts": [
      {
        "phone": "5511999998888",
        "name": "João Silva",
        "birth_date": "1990-05-20",
        "custom_fields": {
          "cidade": "São Paulo",
          "produto_interesse": "plano-anual"
        }
      }
    ]
  }'

// Importa contatos vindos de um CSV / export de CRM
async function importContacts(listName, contacts) {
  const res = await fetch('https://api.zivlo.com.br/v1/contacts/import', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ZIVLO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      list_name: listName,
      upsert: true,
      contacts,
    }),
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.error);
  }

  return await res.json();
}

// Dica: divida em lotes de 500 para listas muito grandes
function chunk(arr, size = 500) {
  const out = [];
  for (let i = 0; i < arr.length; i += size) out.push(arr.slice(i, i + size));
  return out;
}

const allContacts = [
  { phone: '+55 11 99999-8888', name: 'João Silva', tags: ['vip'] },
  { phone: '5511999997777', name: 'Maria Souza' },
  // ... N contatos
];

for (const batch of chunk(allContacts, 500)) {
  const result = await importContacts('Clientes Black Friday', batch);
  console.log(result); // { inserted, updated, skipped, failed, errors }
}

import csv, os, requests
from itertools import islice

URL   = "https://api.zivlo.com.br/v1/contacts/import"
TOKEN = os.environ["ZIVLO_API_KEY"]

def chunks(iterable, size=500):
    it = iter(iterable)
    while batch := list(islice(it, size)):
        yield batch

def import_contacts(list_name, contacts):
    res = requests.post(
        URL,
        headers={"Authorization": f"Bearer {TOKEN}"},
        json={"list_name": list_name, "upsert": True, "contacts": contacts},
    )
    res.raise_for_status()
    return res.json()

# Carrega um CSV com colunas: phone, name, email, cidade
with open("contacts.csv") as f:
    rows = [
        {
            "phone": r["phone"],
            "name": r["name"],
            "email": r["email"],
            "custom_fields": {"cidade": r["cidade"]},
        }
        for r in csv.DictReader(f)
    ]

for batch in chunks(rows, 500):
    result = import_contacts("Clientes Black Friday", batch)
    print(result)  # {'inserted': 420, 'updated': 60, 'skipped': 0, 'failed': 20, 'errors': [...]}

{
  "ok": true,
  "list_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "received": 500,
  "inserted": 420,
  "updated": 60,
  "skipped": 0,
  "failed": 20,
  "errors": [
    { "index": 17, "phone": "+1 555",
      "error": "phone has fewer than 8 digits after normalization" },
    { "index": 92, "phone": "5511999998888",
      "error": "duplicate phone in the same request" }
  ]
}