IAGENTE SDR

API Documentation v1.0

API Online My API Keys

API REST IAGENTE SDR

Integre seu CRM, ERP ou automações com a plataforma IAGENTE SDR. Gerencie leads, envie mensagens e receba eventos em tempo real.

Base URL

https://homolog.sdrbot.ai/api/v1

Versão

v1.0.0

Formato

JSON

Início Rápido

1

Crie uma API Key

Acesse Chaves de API no painel e crie sua primeira chave.

2

Configure a autenticação

Adicione sua API Key no header Authorization de todas as requisições.

3

Faça sua primeira requisição

Use o exemplo abaixo para listar seus leads.

curl -X GET "https://homolog.sdrbot.ai/api/v1/leads" \
  -H "Authorization: Bearer sk_live_sua_chave_aqui" \
  -H "Content-Type: application/json"
import requests

response = requests.get(
    "https://homolog.sdrbot.ai/api/v1/leads",
    headers={"Authorization": "Bearer sk_live_sua_chave_aqui"}
)
leads = response.json()
const response = await fetch("https://homolog.sdrbot.ai/api/v1/leads", {
    headers: {
        "Authorization": "Bearer sk_live_sua_chave_aqui"
    }
});
const leads = await response.json();
$ch = curl_init("https://homolog.sdrbot.ai/api/v1/leads");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_live_sua_chave_aqui"
    ]
]);
$leads = json_decode(curl_exec($ch), true);
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_sua_chave_aqui");

var response = await client.GetAsync("https://homolog.sdrbot.ai/api/v1/leads");
var leads = await response.Content.ReadAsStringAsync();

Authentication

A API utiliza API Keys para autenticação. Inclua sua chave em todas as requisições usando um dos métodos abaixo:

Header Authorization (Recomendado)

Authorization: Bearer sk_live_xxxxxxxxxxxxx

Header X-API-Key (Alternativo)

X-API-Key: sk_live_xxxxxxxxxxxxx

Mantenha sua API Key segura

Nunca exponha sua API Key em código client-side, repositórios públicos ou logs. Em caso de vazamento, regenere a chave imediatamente.

api.errors.title

api.errors.description

api.errors.code api.errors.description_label
400 api.errors.400
401 api.errors.401
404 api.errors.404
409 api.errors.409
422 api.errors.422
429 api.errors.429
500 api.errors.500
Formato de Erro 
{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "details": {
      "phone": ["O campo phone é obrigatório."]
    }
  }
}

Rate Limits

Para garantir a estabilidade da API, aplicamos limites de requisições:

60

requisições por minuto

10.000

requisições por dia

Os headers X-RateLimit-Limit e X-RateLimit-Remaining indicam seu uso atual.

Leads

GET /api/v1/leads List leads

Returns a paginated list of leads from your organization.

Query Parameters

Parameter Type Description
page integer Número da página (default: 1)
per_page integer Itens por página (default: 25, max: 100)
phone string Filter by phone
email string Filter by email
temperature string hot, warm, cool, cold, frozen
sort string Campo de ordenação (prefixo - para desc)
Response 
{
  "data": [
    {
      "id": 123,
      "phone": "5511999999999",
      "name": "Joao Silva",
      "email": "joao@empresa.com",
      "company_name": "Empresa LTDA",
      "temperature": "hot",
      "lead_score": 85
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 150,
    "total_pages": 6
  }
}
POST /api/v1/leads Create lead

Creates a new lead in your organization.

Body Parameters

Field Type Required Description
phone string Sim Telefone com DDD
name string Não Nome do contato
email string Não Email do contato
company_name string Não Nome da empresa
deal_value number Não Valor do negócio 
curl -X POST "https://homolog.sdrbot.ai/api/v1/leads" \
  -H "Authorization: Bearer sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "11999999999",
    "name": "Maria Santos",
    "email": "maria@empresa.com",
    "company_name": "Tech Corp",
    "deal_value": 15000
  }'
import requests

response = requests.post(
    "https://homolog.sdrbot.ai/api/v1/leads",
    headers={"Authorization": "Bearer sk_live_sua_chave"},
    json={
        "phone": "11999999999",
        "name": "Maria Santos",
        "email": "maria@empresa.com",
        "company_name": "Tech Corp",
        "deal_value": 15000
    }
)
lead = response.json()
const response = await fetch("https://homolog.sdrbot.ai/api/v1/leads", {
    method: "POST",
    headers: {
        "Authorization": "Bearer sk_live_sua_chave",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        phone: "11999999999",
        name: "Maria Santos",
        email: "maria@empresa.com",
        company_name: "Tech Corp",
        deal_value: 15000
    })
});
const lead = await response.json();
$ch = curl_init("https://homolog.sdrbot.ai/api/v1/leads");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_live_sua_chave",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "phone" => "11999999999",
        "name" => "Maria Santos",
        "email" => "maria@empresa.com",
        "company_name" => "Tech Corp",
        "deal_value" => 15000
    ])
]);
$lead = json_decode(curl_exec($ch), true);
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_sua_chave");

var payload = new {
    phone = "11999999999",
    name = "Maria Santos",
    email = "maria@empresa.com",
    company_name = "Tech Corp",
    deal_value = 15000
};

var response = await client.PostAsync(
    "https://homolog.sdrbot.ai/api/v1/leads",
    new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json")
);
var lead = await response.Content.ReadAsStringAsync();
GET /api/v1/leads/{id} Get lead

Returns the details of a specific lead.

PUT /api/v1/leads/{id} Update lead

Updates an existing lead.

DELETE /api/v1/leads/{id} Delete lead

Removes a lead from your organization.

WhatsApp

Envie mensagens via WhatsApp Business API. Suporta textos, templates HSM, imagens, videos, documentos e audios.

POST /api/v1/whatsapp/messages Enviar mensagem WhatsApp

Tipos de Mensagem

text template image video document audio

Body Parameters

Field Type Description
lead_id integer ID do lead (ou use phone)
phone string Telefone (ou use lead_id)
type string text, template, image, video, document, audio
text string Texto da mensagem (para type=text)
template_id integer ID do template (para type=template)
template_name string Nome do template (alternativa ao ID)
variables array Variaveis do template ["valor1", "valor2"]
media_url string URL da midia (para tipos de midia)
caption string Legenda da midia (opcional)
filename string Nome do arquivo (para document) 
# Enviar texto
curl -X POST "https://homolog.sdrbot.ai/api/v1/whatsapp/messages" \
  -H "Authorization: Bearer sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "type": "text",
    "text": "Ola! Como posso ajudar?"
  }'

# Enviar template
curl -X POST "https://homolog.sdrbot.ai/api/v1/whatsapp/messages" \
  -H "Authorization: Bearer sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "type": "template",
    "template_name": "boas_vindas",
    "variables": ["Joao"]
  }'
import requests

# Enviar texto
response = requests.post(
    "https://homolog.sdrbot.ai/api/v1/whatsapp/messages",
    headers={"Authorization": "Bearer sk_live_sua_chave"},
    json={
        "phone": "5511999999999",
        "type": "text",
        "text": "Ola! Como posso ajudar?"
    }
)

# Enviar template
response = requests.post(
    "https://homolog.sdrbot.ai/api/v1/whatsapp/messages",
    headers={"Authorization": "Bearer sk_live_sua_chave"},
    json={
        "phone": "5511999999999",
        "type": "template",
        "template_name": "boas_vindas",
        "variables": ["Joao"]
    }
)
// Enviar texto
const response = await fetch("https://homolog.sdrbot.ai/api/v1/whatsapp/messages", {
    method: "POST",
    headers: {
        "Authorization": "Bearer sk_live_sua_chave",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        phone: "5511999999999",
        type: "text",
        text: "Ola! Como posso ajudar?"
    })
});

// Enviar template
const response = await fetch("https://homolog.sdrbot.ai/api/v1/whatsapp/messages", {
    method: "POST",
    headers: {
        "Authorization": "Bearer sk_live_sua_chave",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        phone: "5511999999999",
        type: "template",
        template_name: "boas_vindas",
        variables: ["Joao"]
    })
});
// Enviar texto
$ch = curl_init("https://homolog.sdrbot.ai/api/v1/whatsapp/messages");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_live_sua_chave",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "phone" => "5511999999999",
        "type" => "text",
        "text" => "Ola! Como posso ajudar?"
    ])
]);
$result = json_decode(curl_exec($ch), true);

// Enviar template
$payload = [
    "phone" => "5511999999999",
    "type" => "template",
    "template_name" => "boas_vindas",
    "variables" => ["Joao"]
];
GET /api/v1/whatsapp/templates Listar templates

Lista os templates HSM aprovados pela Meta para sua conta WhatsApp Business.

RCS (Rich Communication Services)

Envie mensagens ricas via RCS com cards, carousels, botoes e quick replies. Oferece experiencia mais interativa que SMS tradicional.

POST /api/v1/rcs/messages Enviar mensagem RCS

Tipos de Mensagem

text file card carousel replyable_text location

Body Parameters

Field Type Description
lead_id integer ID do lead (ou use phone)
phone string Telefone (ou use lead_id)
type string text, file, card, carousel, replyable_text, location
Texto (type=text)
text string Texto da mensagem (max: 4096 caracteres)
Arquivo (type=file)
file_url string URL do arquivo (imagem, video, documento)
mime_type string MIME type (ex: image/jpeg, video/mp4)
Card (type=card)
title string Titulo do card (max: 200 caracteres)
description string Descricao do card
media_url string URL da imagem do card
buttons array Botoes do card (max: 4)
Carousel (type=carousel)
cards array Array de cards (min: 2, max: 10)
card_width string SMALL ou MEDIUM (default: MEDIUM)
Texto com Quick Replies (type=replyable_text)
text string Texto da mensagem
quick_replies array Botoes de resposta rapida (max: 11)
Localizacao (type=location)
latitude number Latitude (-90 a 90)
longitude number Longitude (-180 a 180)
label string Nome do local (opcional) 
curl -X POST "https://homolog.sdrbot.ai/api/v1/rcs/messages" \
  -H "Authorization: Bearer sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "type": "text",
    "text": "Ola! Como posso ajudar?"
  }'
import requests

response = requests.post(
    "https://homolog.sdrbot.ai/api/v1/rcs/messages",
    headers={"Authorization": "Bearer sk_live_sua_chave"},
    json={
        "phone": "5511999999999",
        "type": "text",
        "text": "Ola! Como posso ajudar?"
    }
)
const response = await fetch("https://homolog.sdrbot.ai/api/v1/rcs/messages", {
    method: "POST",
    headers: {
        "Authorization": "Bearer sk_live_sua_chave",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        phone: "5511999999999",
        type: "text",
        text: "Ola! Como posso ajudar?"
    })
});
curl -X POST "https://homolog.sdrbot.ai/api/v1/rcs/messages" \
  -H "Authorization: Bearer sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "type": "card",
    "title": "Produto em Destaque",
    "description": "Confira nossa oferta especial!",
    "media_url": "https://exemplo.com/imagem.jpg",
    "buttons": [
      {"type": "url", "text": "Ver Mais", "url": "https://exemplo.com"},
      {"type": "call", "text": "Ligar", "phone_number": "+5511999999999"}
    ]
  }'
import requests

response = requests.post(
    "https://homolog.sdrbot.ai/api/v1/rcs/messages",
    headers={"Authorization": "Bearer sk_live_sua_chave"},
    json={
        "phone": "5511999999999",
        "type": "card",
        "title": "Produto em Destaque",
        "description": "Confira nossa oferta especial!",
        "media_url": "https://exemplo.com/imagem.jpg",
        "buttons": [
            {"type": "url", "text": "Ver Mais", "url": "https://exemplo.com"},
            {"type": "call", "text": "Ligar", "phone_number": "+5511999999999"}
        ]
    }
)
const response = await fetch("https://homolog.sdrbot.ai/api/v1/rcs/messages", {
    method: "POST",
    headers: {
        "Authorization": "Bearer sk_live_sua_chave",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        phone: "5511999999999",
        type: "card",
        title: "Produto em Destaque",
        description: "Confira nossa oferta especial!",
        media_url: "https://exemplo.com/imagem.jpg",
        buttons: [
            {type: "url", text: "Ver Mais", url: "https://exemplo.com"},
            {type: "call", text: "Ligar", phone_number: "+5511999999999"}
        ]
    })
});
curl -X POST "https://homolog.sdrbot.ai/api/v1/rcs/messages" \
  -H "Authorization: Bearer sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "type": "carousel",
    "card_width": "MEDIUM",
    "cards": [
      {
        "title": "Produto A",
        "description": "Descricao do produto A",
        "media_url": "https://exemplo.com/a.jpg",
        "buttons": [{"type": "url", "text": "Comprar", "url": "https://exemplo.com/a"}]
      },
      {
        "title": "Produto B",
        "description": "Descricao do produto B",
        "media_url": "https://exemplo.com/b.jpg",
        "buttons": [{"type": "url", "text": "Comprar", "url": "https://exemplo.com/b"}]
      }
    ]
  }'
import requests

response = requests.post(
    "https://homolog.sdrbot.ai/api/v1/rcs/messages",
    headers={"Authorization": "Bearer sk_live_sua_chave"},
    json={
        "phone": "5511999999999",
        "type": "carousel",
        "card_width": "MEDIUM",
        "cards": [
            {
                "title": "Produto A",
                "description": "Descricao do produto A",
                "media_url": "https://exemplo.com/a.jpg",
                "buttons": [{"type": "url", "text": "Comprar", "url": "https://exemplo.com/a"}]
            },
            {
                "title": "Produto B",
                "description": "Descricao do produto B",
                "media_url": "https://exemplo.com/b.jpg",
                "buttons": [{"type": "url", "text": "Comprar", "url": "https://exemplo.com/b"}]
            }
        ]
    }
)
const response = await fetch("https://homolog.sdrbot.ai/api/v1/rcs/messages", {
    method: "POST",
    headers: {
        "Authorization": "Bearer sk_live_sua_chave",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        phone: "5511999999999",
        type: "carousel",
        card_width: "MEDIUM",
        cards: [
            {
                title: "Produto A",
                description: "Descricao do produto A",
                media_url: "https://exemplo.com/a.jpg",
                buttons: [{type: "url", text: "Comprar", url: "https://exemplo.com/a"}]
            },
            {
                title: "Produto B",
                description: "Descricao do produto B",
                media_url: "https://exemplo.com/b.jpg",
                buttons: [{type: "url", text: "Comprar", url: "https://exemplo.com/b"}]
            }
        ]
    })
});
curl -X POST "https://homolog.sdrbot.ai/api/v1/rcs/messages" \
  -H "Authorization: Bearer sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "type": "replyable_text",
    "text": "Qual opcao voce prefere?",
    "quick_replies": [
      {"text": "Opcao A", "payload": "option_a"},
      {"text": "Opcao B", "payload": "option_b"},
      {"text": "Falar com atendente", "payload": "human"}
    ]
  }'
import requests

response = requests.post(
    "https://homolog.sdrbot.ai/api/v1/rcs/messages",
    headers={"Authorization": "Bearer sk_live_sua_chave"},
    json={
        "phone": "5511999999999",
        "type": "replyable_text",
        "text": "Qual opcao voce prefere?",
        "quick_replies": [
            {"text": "Opcao A", "payload": "option_a"},
            {"text": "Opcao B", "payload": "option_b"},
            {"text": "Falar com atendente", "payload": "human"}
        ]
    }
)
const response = await fetch("https://homolog.sdrbot.ai/api/v1/rcs/messages", {
    method: "POST",
    headers: {
        "Authorization": "Bearer sk_live_sua_chave",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        phone: "5511999999999",
        type: "replyable_text",
        text: "Qual opcao voce prefere?",
        quick_replies: [
            {text: "Opcao A", payload: "option_a"},
            {text: "Opcao B", payload: "option_b"},
            {text: "Falar com atendente", payload: "human"}
        ]
    })
});

Templates

GET /api/v1/whatsapp/templates List templates

Returns available message templates for use.

Query Parameters

category Filter by category
context Filter by context
meta_approved Apenas aprovados pela Meta (true/false)

Webhooks

Configure Webhooks to receive real-time notifications about events in your account.

POST /api/v1/webhooks Create webhook

Registers a new webhook to receive events.

curl -X POST "https://homolog.sdrbot.ai/api/v1/webhooks" \
  -H "Authorization: Bearer sk_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meu Webhook",
    "url": "https://meusite.com/webhook",
    "events": ["lead.created", "lead.qualified", "message.received"]
  }'
import requests

response = requests.post(
    "https://homolog.sdrbot.ai/api/v1/webhooks",
    headers={"Authorization": "Bearer sk_live_sua_chave"},
    json={
        "name": "Meu Webhook",
        "url": "https://meusite.com/webhook",
        "events": ["lead.created", "lead.qualified", "message.received"]
    }
)
webhook = response.json()
# Guarde o signing_secret retornado!
const response = await fetch("https://homolog.sdrbot.ai/api/v1/webhooks", {
    method: "POST",
    headers: {
        "Authorization": "Bearer sk_live_sua_chave",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        name: "Meu Webhook",
        url: "https://meusite.com/webhook",
        events: ["lead.created", "lead.qualified", "message.received"]
    })
});
const webhook = await response.json();
// Guarde o signing_secret retornado!
$ch = curl_init("https://homolog.sdrbot.ai/api/v1/webhooks");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer sk_live_sua_chave",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "name" => "Meu Webhook",
        "url" => "https://meusite.com/webhook",
        "events" => ["lead.created", "lead.qualified", "message.received"]
    ])
]);
$webhook = json_decode(curl_exec($ch), true);
// Guarde o signing_secret retornado!
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_sua_chave");

var payload = new {
    name = "Meu Webhook",
    url = "https://meusite.com/webhook",
    events = new[] { "lead.created", "lead.qualified", "message.received" }
};

var response = await client.PostAsync(
    "https://homolog.sdrbot.ai/api/v1/webhooks",
    new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json")
);
var webhook = await response.Content.ReadAsStringAsync();
// Guarde o signing_secret retornado!

Important: Save the returned signing_secret. It is used to validate incoming requests.

GET /api/v1/webhooks List webhooks

Returns all configured webhooks.

POST /api/v1/webhooks/{id}/test Test webhook

Sends a test event to the webhook.

Webhook Events

Event Description
lead.created A new lead was created
lead.updated A lead was updated
lead.qualified A lead was qualified
message.received A message was received
message.sent A message was sent
handoff.created A handoff was created
handoff.closed A handoff was closed

Verify Signature

Validate the X-Webhook-Signature header to ensure the request was sent by IAGENTE.

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$secret = 'whsec_seu_secret_aqui';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (hash_equals($expected, $signature)) {
    // Assinatura valida - processar evento
    $event = json_decode($payload, true);
} else {
    // Assinatura invalida - rejeitar
    http_response_code(401);
}
import hmac
import hashlib
from flask import request, abort

def verify_webhook():
    payload = request.get_data()
    signature = request.headers.get('X-Webhook-Signature')
    secret = 'whsec_seu_secret_aqui'

    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    if hmac.compare_digest(expected, signature):
        # Assinatura valida - processar evento
        event = request.get_json()
        return event
    else:
        # Assinatura invalida - rejeitar
        abort(401)
const crypto = require('crypto');

function verifyWebhook(req) {
    const payload = req.rawBody; // Buffer do body
    const signature = req.headers['x-webhook-signature'];
    const secret = 'whsec_seu_secret_aqui';

    const expected = 'sha256=' + crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');

    if (crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
        // Assinatura valida - processar evento
        const event = JSON.parse(payload);
        return event;
    } else {
        // Assinatura invalida - rejeitar
        throw new Error('Invalid signature');
    }
}
using System.Security.Cryptography;
using System.Text;

public bool VerifyWebhook(string payload, string signature)
{
    var secret = "whsec_seu_secret_aqui";

    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));
    var expected = "sha256=" + BitConverter.ToString(hash).Replace("-", "").ToLower();

    if (CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(expected),
        Encoding.UTF8.GetBytes(signature)))
    {
        // Assinatura valida - processar evento
        return true;
    }

    // Assinatura invalida - rejeitar
    return false;
}