DEVELOPER EXPERIENCE

Entenda a integração antes do código.

Um resumo do fluxo de integração e o caminho para a referência completa da API v1.

Vá direto à referência.

Endpoints, campos, eventos e códigos de erro da API v1, com exemplos em curl, Node.js e PHP.

Acessar documentação técnica

Os exemplos usam valores fictícios. Faça as chamadas a partir do seu backend, com a sua chave de API.

Enviar uma mensagem de texto

Contrato público v1. Execute no seu backend com uma instância conectada e acesso ativo. O retorno 202 aceita o processamento; não confirma entrega.

curl
curl --request POST "https://app.connect.mydev.com.br/api/v1/instances/INSTANCE_ID/messages" \
  --header "Authorization: Bearer $CONNECT_TOKEN" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"to":"DESTINATARIO","text":"Olá!"}'
JavaScript (Node.js)
const response = await fetch(
  `https://app.connect.mydev.com.br/api/v1/instances/${process.env.CONNECT_INSTANCE_ID}/messages`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.CONNECT_TOKEN}`,
      Accept: 'application/json',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ to: process.env.CONNECT_TO, text: 'Olá!' }),
  },
);
if (!response.ok) throw new Error(`Connect: HTTP ${response.status}`);
const result = await response.json();
PHP (cURL)
$instance = rawurlencode(getenv('CONNECT_INSTANCE_ID'));
$ch = curl_init("https://app.connect.mydev.com.br/api/v1/instances/$instance/messages");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.getenv('CONNECT_TOKEN'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['to' => getenv('CONNECT_TO'), 'text' => 'Olá!']),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($body === false || $status >= 400) throw new RuntimeException('Falha ao enviar pelo Connect');
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);

Substitua os placeholders. Nunca exponha tokens no navegador. Referência técnica e erros.

SEU CHECKLIST TÉCNICO

Antes de ir para produção.

Acesso e segurança

Guarde a chave em um gerenciador de segredos e chame a API só pelo servidor. Defina validade e revogue chaves que não usa mais.

Contratos e limites

Envie Accept: application/json, respeite 16 MB para mídia e 50 MB para documentos e pagine o histórico em até 100 itens.

Eventos e falhas

Responda 2xx em até 10 segundos, valide a assinatura, descarte duplicatas pelo X-Connect-Delivery e reconcilie por polling.

Introdução

A API v1 usa a base https://app.connect.mydev.com.br/api/v1, JSON e autenticação Bearer. O Connect gerencia instâncias e o transporte das mensagens; regras de negócio, chatbot e experiência continuam na sua aplicação.

Primeira integração

Crie a conta e gere uma chave em Chaves de API. Depois crie uma instância, inicie a conexão, escaneie o QR Code e consulte o status até a sessão abrir. Com a instância conectada, envie a primeira mensagem.

Primeiros passos · API v1
  1. 01Cadastro e chave
  2. 02Criar instância
  3. 03Conectar via QR
  4. 04Enviar texto

Autenticação

Envie Authorization: Bearer mc_<sua-chave> em todas as chamadas, exceto GET /health. O Connect guarda só o hash; o token completo aparece uma única vez. Nunca exponha a chave no frontend.

Instâncias

Uma instância é uma conexão com um número de WhatsApp. Crie com POST /instances, conecte com POST /instances/{instance}/connect e acompanhe GET /instances/{instance}/status. Conectar e enviar exige assinatura ativa ou teste válido.

Envio de mensagens

POST /instances/{instance}/messages aceita texto ou arquivo (imagem, áudio, vídeo ou documento) por media_url ou media_base64. A resposta 202 devolve o id com status pending; a entrega é confirmada pelo evento message.status.

Recebimento de mensagens

Mensagens recebidas chegam pelo evento message.received com remetente, tipo, texto e, quando houver, link para baixar o arquivo. O link vale 7 dias e os arquivos ficam guardados por 30 dias.

Webhooks e eventos

Configure webhook_url na instância e valide X-Connect-Signature com HMAC-SHA256 sobre o corpo bruto e webhook_secret. Use X-Connect-Delivery para deduplicação. Os eventos são message.received, message.status e instance.status. Sem resposta 2xx, o Connect tenta de novo até 5 vezes.

Fluxo de eventos documentado na API v1
  1. 01WhatsApp
  2. 02Connect
  3. 03Webhook
  4. 04Seu sistema

Tratamento de erros

401 indica chave inválida ou revogada, 402 exige assinatura, 403 conta indisponível, 404 instância não encontrada e 422 dados inválidos, com detalhes em errors. Para 5xx, tente de novo com espera progressiva.

Exemplos de integração

Os exemplos acima seguem o contrato público v1 de envio de texto. Configure token, instância conectada e destinatário no seu backend. A referência completa traz exemplos de arquivos, webhooks e validação de assinatura.

Limites e boas práticas

A quantidade de instâncias depende do plano. Planeje contingência para desconexões e restrições inerentes à integração não oficial, e acompanhe o evento instance.status.

Ver todos os recursos →

SEU PRÓXIMO BUILD COMEÇA AQUI

Você constrói.
A conversa continua.

Vamos encontrar o lugar da comunicação no seu produto.