API para Desenvolvedores

Início Rápido

Abaixo você encontrará a documentação detalhada para o endpoint de envio de mensagens WhatsApp. Para começar a utilizar, você precisa ter uma API key válida e conhecer a URL base para as requisições.

URL Base

https://api.ai-desk.com.br

Exemplo Básico de Envio de Mensagem (cURL)

curl -X POST https://api.ai-desk.com.br/send-message \
  -H "Content-Type: application/json" \
  -H "apikey: sua_api_key_aqui" \
  -d '{
    "number": "5511978049825",
    "template_id": 15,
    "variables": {
      "nome": "João",
      "codigo": "ABC123"
    },
    "queue_id": 5,
    "status_id": 1
  }'

Autenticação

Todas as requisições devem incluir a API key no cabeçalho HTTP:

apikey: sua_api_key_aqui

Fluxo de Execução

1. Validação da API Key: Verifica se a key fornecida é válida
2. Validação de Parâmetros: Confirma todos os parâmetros obrigatórios
3. Processamento de Template/Campanha: Busca template ou campanha fornecido
4. Substituição de Variáveis: Aplica variáveis ao texto do template
5. Envio via API do WhatsApp: Envia através da Graph API da Meta
6. Persistência no Banco: Salva contato, conversa e mensagem
7. Resposta: Retorna ID da mensagem ou erro detalhado

Boas Práticas

1. Use Templates Oficiais Aprovados: Para garantir a entrega das mensagens
2. Evite Spam: Envie apenas mensagens relevantes e esperadas
3. Respeite a Janela de 24h: Para interações posteriores com o contato
4. Trate Erros: Especialmente de API (400 e 401) que podem indicar problemas de configuração
5. Controle Fluxo: Não faça disparos em massa simultâneos

Regras de Negócio

1. Contatos: Serão criados automaticamente se não existirem
2. Conversas: Serão criadas com os IDs de fila e status fornecidos
3. Nome de Contato: Será atualizado se um novo for enviado
4. Números: Devem incluir código do país sem formatação (ex: 5511978049825)
5. Apenas Templates: A API só suporta envio via templates para conformidade com WhatsApp

Mais Endpoints

Estamos trabalhando para disponibilizar a documentação completa para todos os endpoints da plataforma AI DESK:

Fique de olho nesta página para atualizações ou entre em contato com nosso suporte para mais informações.

Sobre os Endpoints de Envio

A plataforma AI DESK oferece dois tipos de endpoints para envio de mensagens WhatsApp:

• Envio via Template/Campanha: Ideal para disparos em massa, campanhas e uso de templates aprovados pela Meta.
• Envio Direto de Mensagens & Mídias: Para envio individual de mensagens de texto ou mídia para contatos específicos, vinculado a uma instância.

Consulte abaixo a documentação detalhada de cada um.

Envio via Template/Campanha

Endpoint para envio de mensagens WhatsApp utilizando templates pré-aprovados pela Meta ou campanhas organizadas em seu painel.

URL:

POST https://api.ai-desk.com.br/send-message

Headers obrigatórios

Content-Type: application/json
apikey: sua_api_key_aqui

Parâmetros Obrigatórios

Parâmetro	Tipo	Descrição
number	string	Número de telefone com código do país (55...) sem símbolos
queue_id	integer	ID da fila para associar a mensagem/conversa
status_id	integer	ID do status para a conversa

E obrigatoriamente UM dos seguintes:

Parâmetro	Tipo	Descrição
template_id	integer	ID do template pré-definido no banco de dados
campaign_id	integer	ID da campanha que contém um template

Parâmetros Opcionais

Parâmetro	Tipo	Descrição
contact_name	string	Nome do contato para criar/atualizar no sistema
variables	object	Objeto com variáveis para templates {"chave":"valor"}

Exemplo de Envio via Template

curl -X POST https://api.ai-desk.com.br/send-message \
  -H "Content-Type: application/json" \
  -H "apikey: sua_api_key_aqui" \
  -d '{
    "number": "5511978049825",
    "template_id": 15,
    "variables": {
      "nome": "João",
      "codigo": "ABC123"
    },
    "queue_id": 5,
    "status_id": 1
  }'

Exemplo de Envio via Campanha

curl -X POST https://api.ai-desk.com.br/send-message \
  -H "Content-Type: application/json" \
  -H "apikey: sua_api_key_aqui" \
  -d '{
    "number": "5511978049825",
    "campaign_id": 3,
    "variables": {
      "nomeCliente": "João",
      "codigo": "ABC123"
    },
    "queue_id": 5,
    "status_id": 1
  }'

Resposta de Sucesso

{
  "success": true,
  "message_id": "wamid.HBgLNTExOTc4MDQ5ODI1FQIAERgSMTIzNDU2Nzg5MDEyMzQ1Njc4"
}

Envio Direto de Mensagens & Mídias

API para envio individual de mensagens de texto e mídia para contatos do WhatsApp vinculados a uma instância específica.

URL:

POST https://api.aideskbr.com/sendmessage

Headers obrigatórios

Content-Type: application/json
apikey: SUA_API_KEY_AQUI

Envio de mensagem de texto

Exemplo de payload

{
  "contact_id": 53,
  "instance_id": 4,
  "message_content": "Olá, tudo bem?"
}

Campo	Tipo	Descrição
contact_id	integer	ID do contato (deve pertencer à instance_id)
instance_id	integer	ID da instância
message_content	string	Texto da mensagem

Envio de mensagem de mídia

Exemplo de payload

{
  "contact_id": 53,
  "instance_id": 4,
  "media_url": "https://meusite.com/arquivo.pdf",
  "media_caption": "Segue o documento solicitado."
}

Campo	Tipo	Descrição
contact_id	integer	ID do contato (deve pertencer à instance_id)
instance_id	integer	ID da instância
media_url	string	URL pública do arquivo de mídia (imagem, vídeo, áudio ou documento)
media_caption	string (opcional)	Legenda da mídia

Resposta de sucesso

{
  "status": "success",
  "message": "Mensagem enviada com sucesso",
  "whatsapp_message_id": "wamid.XXXX...",
  "media_type": "text" | "image" | "video" | "audio" | "document",
  "media_file_id": "",
  "source": "api"
}

Possíveis erros

• 400: Payload inválido, campos obrigatórios ausentes ou contact_id não pertence à instance_id
• 401: API key inválida ou não autorizada para a instance_id
• 500: Erro interno do servidor

Exemplo de requisição (cURL)

Texto

curl -X POST https://api.aideskbr.com/sendmessage \
  -H "Content-Type: application/json" \
  -H "apikey: SUA_API_KEY_AQUI" \
  -d '{
    "contact_id": 53,
    "instance_id": 4,
    "message_content": "Olá, tudo bem?"
  }'

Mídia

curl -X POST https://api.aideskbr.com/sendmessage \
  -H "Content-Type: application/json" \
  -H "apikey: SUA_API_KEY_AQUI" \
  -d '{
    "contact_id": 53,
    "instance_id": 4,
    "media_url": "https://meusite.com/arquivo.pdf",
    "media_caption": "Segue o documento solicitado."
  }'

Se precisar de mais exemplos ou detalhes, entre em contato com o suporte técnico da Aidesk.