Gerenciamento de instancias WhatsApp Business — CRUD, ativacao, phone numbers e autenticacao admin

Instancias

Endpoints para gerenciar instancias WhatsApp Business no connector. Cada instancia representa um numero de telefone conectado via Meta Cloud API.

Autenticacao Admin

Os endpoints /admin/* usam JWT obtido via login. Os endpoints /instance/* usam API key.

POST /admin/auth/login

Autentica o administrador e retorna um token JWT.

Auth: Publico (sem header de autenticacao).

Request Body:

{
  "username": "admin",
  "password": "sua-senha"
}

Curl:

curl -X POST http://localhost:8200/admin/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "sua-senha"
  }'

Resposta (200 OK):

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "username": "admin"
}

Use o token retornado como Authorization: Bearer <JWT_TOKEN> nos demais endpoints admin.

GET /admin/instances

Lista todas as instancias cadastradas.

Auth: Authorization: Bearer <JWT_TOKEN>

Curl:

curl http://localhost:8200/admin/instances \
  -H "Authorization: Bearer <JWT_TOKEN>"

Resposta (200 OK):

[
  {
    "id": "uuid-da-instancia",
    "name": "MAZAM Principal",
    "phone_number_id": "123456789",
    "waba_id": "987654321",
    "display_phone_number": "+5511999998888",
    "verified_name": "MAZAM Financeira",
    "quality_rating": "GREEN",
    "messaging_limit_tier": "TIER_1K",
    "is_active": true,
    "status": "connected",
    "token_type": "system_user",
    "created_at": "2026-04-01T10:00:00Z",
    "updated_at": "2026-04-01T10:00:00Z"
  }
]

POST /admin/instances

Cria uma nova instancia.

Auth: Authorization: Bearer <JWT_TOKEN>

Request Body:

{
  "name": "MAZAM Principal",
  "phone_number_id": "123456789",
  "waba_id": "987654321",
  "access_token": "EAABs...",
  "token_type": "system_user",
  "business_id": "111222333",
  "meta_app_id": "444555666"
}

Campo	Tipo	Obrigatorio	Descricao
`name`	string	Sim	Nome identificador da instancia
`phone_number_id`	string	Sim	Phone Number ID da Meta
`waba_id`	string	Sim	WhatsApp Business Account ID
`access_token`	string	Sim	Token de acesso (System User ou OAuth)
`token_type`	string	Sim	`system_user` ou `oauth`
`business_id`	string	Nao	Business ID da Meta
`meta_app_id`	string	Nao	App ID da Meta

Curl:

curl -X POST http://localhost:8200/admin/instances \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MAZAM Principal",
    "phone_number_id": "123456789",
    "waba_id": "987654321",
    "access_token": "EAABs...",
    "token_type": "system_user"
  }'

Resposta (201 Created):

{
  "id": "uuid-gerado",
  "name": "MAZAM Principal",
  "phone_number_id": "123456789",
  "waba_id": "987654321",
  "is_active": true,
  "status": "connected",
  "created_at": "2026-04-04T10:00:00Z"
}

Seguranca: O access_token e armazenado criptografado (AES-256-GCM) no banco de dados.

GET /admin/instances/{id}

Retorna detalhes de uma instancia especifica.

Auth: Authorization: Bearer <JWT_TOKEN>

Curl:

curl http://localhost:8200/admin/instances/uuid-da-instancia \
  -H "Authorization: Bearer <JWT_TOKEN>"

Resposta (200 OK):

{
  "id": "uuid-da-instancia",
  "name": "MAZAM Principal",
  "phone_number_id": "123456789",
  "waba_id": "987654321",
  "business_id": "111222333",
  "display_phone_number": "+5511999998888",
  "verified_name": "MAZAM Financeira",
  "quality_rating": "GREEN",
  "messaging_limit_tier": "TIER_1K",
  "is_active": true,
  "status": "connected",
  "token_type": "system_user",
  "meta_app_id": "444555666",
  "webhook_verify_token": "random-verify-token",
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-04-01T10:00:00Z"
}

PATCH /admin/instances/{id}

Atualiza campos de uma instancia existente. Envie apenas os campos que deseja alterar.

Auth: Authorization: Bearer <JWT_TOKEN>

Request Body (parcial):

{
  "name": "MAZAM Atendimento",
  "access_token": "EAABs-novo-token..."
}

Curl:

curl -X PATCH http://localhost:8200/admin/instances/uuid-da-instancia \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MAZAM Atendimento"
  }'

Resposta (200 OK):

{
  "id": "uuid-da-instancia",
  "name": "MAZAM Atendimento",
  "updated_at": "2026-04-04T12:00:00Z"
}

DELETE /admin/instances/{id}

Remove uma instancia permanentemente.

Auth: Authorization: Bearer <JWT_TOKEN>

Curl:

curl -X DELETE http://localhost:8200/admin/instances/uuid-da-instancia \
  -H "Authorization: Bearer <JWT_TOKEN>"

Resposta (200 OK):

{
  "success": true,
  "message": "Instance deleted"
}

POST /admin/instances/{id}/activate

Ativa uma instancia desativada. Reconecta o client com a Meta Cloud API.

Auth: Authorization: Bearer <JWT_TOKEN>

Curl:

curl -X POST http://localhost:8200/admin/instances/uuid-da-instancia/activate \
  -H "Authorization: Bearer <JWT_TOKEN>"

Resposta (200 OK):

{
  "success": true,
  "status": "connected"
}

POST /admin/instances/{id}/deactivate

Desativa uma instancia. Para de processar mensagens para este numero.

Auth: Authorization: Bearer <JWT_TOKEN>

Curl:

curl -X POST http://localhost:8200/admin/instances/uuid-da-instancia/deactivate \
  -H "Authorization: Bearer <JWT_TOKEN>"

Resposta (200 OK):

{
  "success": true,
  "status": "disconnected"
}

GET /admin/instances/status/all

Retorna o status de todas as instancias de forma resumida.

Auth: Authorization: Bearer <JWT_TOKEN>

Curl:

curl http://localhost:8200/admin/instances/status/all \
  -H "Authorization: Bearer <JWT_TOKEN>"

Resposta (200 OK):

{
  "total": 3,
  "active": 2,
  "inactive": 1,
  "instances": [
    {
      "id": "uuid-1",
      "name": "MAZAM Principal",
      "is_active": true,
      "status": "connected",
      "quality_rating": "GREEN"
    },
    {
      "id": "uuid-2",
      "name": "MAZAM Suporte",
      "is_active": true,
      "status": "connected",
      "quality_rating": "YELLOW"
    },
    {
      "id": "uuid-3",
      "name": "MAZAM Marketing",
      "is_active": false,
      "status": "disconnected",
      "quality_rating": "GREEN"
    }
  ]
}

Phone Numbers

Endpoints para gerenciar numeros de telefone da WhatsApp Business Account. Usam autenticacao por API key.

Auth: Authorization: Bearer <API_KEY>

GET /instance/phone_numbers

Lista todos os numeros de telefone registrados na WABA.

Query Parameters:

Parametro	Tipo	Obrigatorio	Descricao
`instance_id`	string	Sim	UUID da instancia

Curl:

curl "http://localhost:8200/instance/phone_numbers?instance_id=uuid-da-instancia" \
  -H "Authorization: Bearer <API_KEY>"

Resposta (200 OK):

{
  "data": [
    {
      "id": "123456789",
      "display_phone_number": "+5511999998888",
      "verified_name": "MAZAM Financeira",
      "quality_rating": "GREEN",
      "code_verification_status": "VERIFIED",
      "messaging_limit_tier": "TIER_1K"
    }
  ]
}

POST /instance/register

Registra um numero de telefone na Meta Cloud API. Necessario apos adicionar um novo numero via Embedded Signup.

Request Body:

{
  "instance_id": "uuid-da-instancia",
  "pin": "123456"
}

Campo	Tipo	Obrigatorio	Descricao
`instance_id`	string	Sim	UUID da instancia
`pin`	string	Sim	PIN de 6 digitos para registro

Curl:

curl -X POST http://localhost:8200/instance/register \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "uuid-da-instancia",
    "pin": "123456"
  }'

Resposta (200 OK):

{
  "success": true
}

POST /instance/request_code

Solicita um codigo de verificacao via SMS ou chamada de voz para o numero.

Request Body:

{
  "instance_id": "uuid-da-instancia",
  "code_method": "SMS",
  "language": "pt_BR"
}

Campo	Tipo	Obrigatorio	Descricao
`instance_id`	string	Sim	UUID da instancia
`code_method`	string	Sim	`SMS` ou `VOICE`
`language`	string	Sim	Codigo do idioma (ex: `pt_BR`)

Curl:

curl -X POST http://localhost:8200/instance/request_code \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "uuid-da-instancia",
    "code_method": "SMS",
    "language": "pt_BR"
  }'

Resposta (200 OK):

{
  "success": true
}

POST /instance/verify_code

Verifica o codigo recebido por SMS ou chamada de voz.

Request Body:

{
  "instance_id": "uuid-da-instancia",
  "code": "123456"
}

Campo	Tipo	Obrigatorio	Descricao
`instance_id`	string	Sim	UUID da instancia
`code`	string	Sim	Codigo de verificacao recebido

Curl:

curl -X POST http://localhost:8200/instance/verify_code \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "uuid-da-instancia",
    "code": "123456"
  }'

Resposta (200 OK):

{
  "success": true
}

Este guia foi útil?

Última atualização: 7 de abril de 2026

Instancias

On this page