Primeiros Passos

Este guia vai te ajudar a criar sua primeira instancia, conectar um numero WhatsApp e enviar sua primeira mensagem.

Pre-requisitos

NeoGo rodando (local ou servidor) na porta 4000
Uma GLOBAL_API_KEY configurada no servidor (variavel de ambiente)
Um numero de WhatsApp para conectar
curl ou qualquer cliente HTTP (Postman, Insomnia, etc.)

Dica: Todas as requisicoes usam o header apikey para autenticacao. Rotas administrativas usam a chave global, rotas de instancia usam o token retornado na criacao.

API Versionada: Todos os endpoints estao disponiveis com o prefixo /api/v1/ (recomendado). Exemplo: POST /api/v1/send/text. As rotas sem prefixo (POST /send/text) continuam funcionando, mas estao marcadas como deprecated e serao removidas a partir de 2027-01-01. Respostas nas rotas legadas incluem os headers Deprecation: true e Sunset: 2027-01-01.

Criar uma Instancia

Uma instancia representa uma sessao do WhatsApp. Voce pode criar quantas precisar.

cURL

Python

Node.js

curl -X POST http://localhost:4000/instance/create \
  -H "apikey: SUA_CHAVE_GLOBAL" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "meu-whatsapp",
    "webhookUrl": "https://meusite.com/webhook"
  }'

import requests

resp = requests.post(
    "http://localhost:4000/instance/create",
    headers={
        "apikey": "SUA_CHAVE_GLOBAL",
        "Content-Type": "application/json"
    },
    json={
        "instanceName": "meu-whatsapp",
        "webhookUrl": "https://meusite.com/webhook"
    }
)
data = resp.json()
print(f"Token: {data['token']}")
print(f"Instance ID: {data['instanceId']}")

const resp = await fetch("http://localhost:4000/instance/create", {
  method: "POST",
  headers: {
    "apikey": "SUA_CHAVE_GLOBAL",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    instanceName: "meu-whatsapp",
    webhookUrl: "https://meusite.com/webhook"
  })
});
const data = await resp.json();
console.log("Token:", data.token);
console.log("Instance ID:", data.instanceId);

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]string{
        "instanceName": "meu-whatsapp",
        "webhookUrl":   "https://meusite.com/webhook",
    })
    req, _ := http.NewRequest("POST", "http://localhost:4000/instance/create", bytes.NewBuffer(body))
    req.Header.Set("apikey", "SUA_CHAVE_GLOBAL")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println("Token:", result["token"])
    fmt.Println("Instance ID:", result["instanceId"])
}

A resposta inclui um token unico para essa instancia. Guarde esse token — ele sera usado em todas as requisicoes subsequentes.

{
  "instanceId": "abc123-...",
  "instanceName": "meu-whatsapp",
  "token": "9f4e2d1a8b7c6e5f...",
  "webhookUrl": "https://meusite.com/webhook",
  "status": "created"
}

Conectar o WhatsApp (QR Code)

Apos criar a instancia, voce precisa conectar um numero de WhatsApp. Existem duas formas: QR Code ou Pairing Code.

Opcao A: QR Code

# 1. Iniciar conexao
curl -X POST http://localhost:4000/instance/connect \
  -H "apikey: TOKEN_DA_INSTANCIA"

# 2. Obter QR code (retorna base64 da imagem)
curl http://localhost:4000/instance/qr \
  -H "apikey: TOKEN_DA_INSTANCIA"

Abra o WhatsApp no celular → Configuracoes → Aparelhos Conectados → Conectar Aparelho → Escaneie o QR code.

Opcao B: Pairing Code (sem QR)

curl -X POST http://localhost:4000/instance/pair \
  -H "apikey: TOKEN_DA_INSTANCIA" \
  -H "Content-Type: application/json" \
  -d '{"number": "5511999999999"}'

O servidor retorna um codigo de 8 digitos. No celular: Configuracoes → Aparelhos Conectados → Conectar Aparelho → Conectar com numero de telefone → Digite o codigo.

Verificar Status

curl http://localhost:4000/instance/status \
  -H "apikey: TOKEN_DA_INSTANCIA"

# Resposta quando conectado:
# {"status": "CONNECTED", "number": "5511999999999"}

Enviar Primeira Mensagem

Com a instancia conectada, voce pode enviar mensagens para qualquer numero.

cURL

Python

Node.js

curl -X POST http://localhost:4000/send/text \
  -H "apikey: TOKEN_DA_INSTANCIA" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511888888888",
    "text": "Ola! Esta e minha primeira mensagem via NeoGo API."
  }'

import requests

resp = requests.post(
    "http://localhost:4000/send/text",
    headers={
        "apikey": "TOKEN_DA_INSTANCIA",
        "Content-Type": "application/json"
    },
    json={
        "number": "5511888888888",
        "text": "Ola! Esta e minha primeira mensagem via NeoGo API."
    }
)
print(resp.json())

const resp = await fetch("http://localhost:4000/send/text", {
  method: "POST",
  headers: {
    "apikey": "TOKEN_DA_INSTANCIA",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number: "5511888888888",
    text: "Ola! Esta e minha primeira mensagem via NeoGo API."
  })
});
console.log(await resp.json());

body, _ := json.Marshal(map[string]string{
    "number": "5511888888888",
    "text":   "Ola! Esta e minha primeira mensagem via NeoGo API.",
})
req, _ := http.NewRequest("POST", "http://localhost:4000/send/text", bytes.NewBuffer(body))
req.Header.Set("apikey", "TOKEN_DA_INSTANCIA")
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
// handle response...

Formato do numero: Use apenas digitos, incluindo o codigo do pais (55 para Brasil). Exemplos: 5511999999999 (celular SP), 5521888888888 (celular RJ). A API normaliza automaticamente para o formato JID do WhatsApp.

Receber Webhooks

Configure uma URL de webhook para receber eventos em tempo real (mensagens recebidas, status de conexao, etc.).

Se voce definiu webhookUrl ao criar a instancia, os eventos ja serao enviados para la. Caso contrario, configure depois:

# A URL de webhook e definida na criacao da instancia.
# Para testar localmente, use ngrok ou similar:
ngrok http 3000

# Exemplo de servidor para receber webhooks (Node.js):
const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  const event = req.body;
  console.log(`Evento: ${event.event}`);
  console.log(`Dados:`, event.data);

  // Verificar assinatura HMAC (opcional, mas recomendado)
  const signature = req.headers['x-webhook-signature'];
  // ... validar com sua chave

  res.sendStatus(200);
});

app.listen(3000);

Veja a documentacao completa de webhooks em Webhooks.

Outros Tipos de Envio

Alem de texto, a NeoGo API suporta diversos tipos de mensagem:

Tipo	Endpoint	Descricao
Texto	`POST /send/text`	Mensagem de texto simples
Midia	`POST /send/media`	Imagem, video, audio ou documento
Link	`POST /send/link`	Link com preview
Localizacao	`POST /send/location`	Coordenadas GPS
Contato	`POST /send/contact`	Cartao de contato (vCard)
Botao	`POST /send/button`	Mensagem com botoes interativos
Lista	`POST /send/list`	Menu de opcoes em lista
Enquete	`POST /send/poll`	Enquete com multiplas opcoes
Sticker	`POST /send/sticker`	Figurinha (WebP)
Pix	`POST /send/pix`	Chave Pix para pagamento
Carrossel	`POST /send/carousel`	Cards horizontais com botoes
Forward	`POST /send/forward`	Encaminhar mensagem existente
Batch	`POST /send/batch/text`	Envio em massa de texto
Status (texto)	`POST /send/status/text`	Publicar texto no status/stories
Status (midia)	`POST /send/status/media`	Publicar midia no status/stories

Proximos Passos

Autenticacao — Entenda a diferenca entre admin key e instance token
Webhooks — Configure e valide eventos em tempo real
API Reference — Explore todos os endpoints interativamente
Manager UI — Gerencie instancias pela interface visual