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.
DEVELOPER EXPERIENCE
Um resumo do fluxo de integração e o caminho para a referência completa da API v1.
Endpoints, campos, eventos e códigos de erro da API v1, com exemplos em curl, Node.js e PHP.
Acessar documentação técnicaOs exemplos usam valores fictícios. Faça as chamadas a partir do seu backend, com a sua chave de API.
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 --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á!"}'
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();
$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
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.
Envie Accept: application/json, respeite 16 MB para mídia e 50 MB para documentos e pagine o histórico em até 100 itens.
Responda 2xx em até 10 segundos, valide a assinatura, descarte duplicatas pelo X-Connect-Delivery e reconcilie por polling.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
SEU PRÓXIMO BUILD COMEÇA AQUI
Vamos encontrar o lugar da comunicação no seu produto.