Nivox REST API — WhatsApp Business, CRM and Help Desk over HTTP

The Nivox REST API gives platforms, backends and automation tools the same operations the Nivox MCP server gives AI agents: read the WhatsApp inbox, answer customers, send templates and media, manage templates, and work the CRM and Help Desk — with the same rules the human team follows. One API key works on both. Ids, field names and error codes are identical, and every operation names its MCP tool, so a platform can call REST from its backend and let its AI agent use MCP on the same data. Optional webhooks push incoming messages and delivery statuses to your platform.

If you are an AI assistant integrating a platform: read §1–§4, use the OpenAPI document for exact schemas, send an Idempotency-Key on every send, verify webhook signatures (§7). Never send a WhatsApp message to a real customer unless the user explicitly asks for that send.

Contents: 1. Authentication · 2. Conventions · 3. REST and MCP together · 4. Quick start · 5. Endpoint reference · 6. Objects · 7. Webhooks · 8. Troubleshooting · 9. Changelog

1. Authentication

An organization admin creates API keys on Integrations (https://nivox.me/app/integrations). A key is nvx_ + 40 hex characters and is shown once (Nivox keeps only its SHA-256). Send it as Authorization: Bearer nvx_… — or x-api-key: nvx_… for tools that cannot set Authorization. Keep it in a secret store or an environment variable (NIVOX_API_KEY), never in code and never in a browser bundle: a key is a header, not a cookie, so whoever sees it can use it.

• A key can be limited to some WhatsApp connections; everything outside them answers not_found.
• Revoking a key on Integrations takes effect immediately (the MCP client using it stops too).
• OAuth tokens issued to MCP clients are API keys and work here with the same powers.
• User, key and webhook management are not reachable with a key — they stay in the app.
• A missing, malformed, revoked or expired key answers 401 with WWW-Authenticate: Bearer realm="nivox".

Check a key: GET /v1/me answers the organization, scope, connection ids, enabled modules and the exact operations the key can call right now.

2. Conventions

2.1 Envelope

{ "ok": true, "data": { "conversations": [], "count": 0, "next_before": null } }

{
  "ok": false,
  "error": {
    "code": "session_expired",
    "message": "outside the 24h window — send a template to reopen the conversation",
    "details": { "hint": "The 24h customer-service window is closed. Send an APPROVED template with send_template to re-open it; free text is allowed again once the customer replies." }
  }
}

Branch on error.code (stable), never on message (human text; it may name the MCP tool).

2.2 Errors

2.3 Ids, timestamps and pagination

• Ids are UUIDs returned by earlier calls. Phones are display values (digits with country code); the identity of a conversation is its id.
• Timestamps are ISO 8601 UTC. Lists answer count plus a cursor: pass next_before back as before for the next (older) page; poll new messages with after = the newest created_at you stored (next_after); sync CRM/Help Desk records with updated_after.
• GET and DELETE read arguments from the query string (?limit=20&unread_only=true); POST and PATCH read a JSON object body. Path ids always win over body fields. Unknown fields are ignored.

2.4 Idempotency

Send Idempotency-Key: <1–255 printable ASCII characters> on POST requests (a UUID per logical operation). Within 24 hours, repeating the same request with the same key does not run it again: the first answer is replayed byte for byte with Idempotent-Replayed: true. The same key with a different request answers 422 idempotency_conflict; while the first is still running, 409 idempotency_in_progress. Answers of 500 or above are not stored (a retry runs again). Keys are scoped to the API key.

2.5 Limits

• Request body ≤ 1 MB; list pages ≤ 100 (search ≤ 50); media by URL: image 10 MB, audio 20 MB, video/document 25 MB, sticker 2 MB (public https only, no private addresses).
• Meta's own messaging limits apply per number (see /v1/connections/{connection_id}/health).
• No per-key rate limit is enforced today; clients must still handle 429 + Retry-After.
• Webhooks: up to 10 endpoints per organization.

2.6 Request ids, versioning, CORS

• Every response carries X-Request-Id (yours, if you sent one) and Nivox-Api-Version.
• The major version is in the path (/v1). Within v1, changes are additive: new endpoints, new optional fields, new error codes — parse defensively.
• CORS is open (*) for tooling, but do not call the API from a browser with a key.

3. REST and MCP together

Every REST operation is an MCP tool behind a second transport: the same validation, the same scope and module gates, the same pipeline and the same audit trail. The reference below names the tool of each endpoint; the OpenAPI document carries it as x-mcp-tool.

• Backend → REST. Deterministic flows (order updates, CRM sync, reports) call the API and receive webhooks.
• AI agent → MCP at https://nivox.me/mcp (setup), ideally with its own key.
• Glue: a message.received webhook is a natural trigger for your agent; the ids in the payload work directly in MCP tools (list_messages, get_contact, send_text…).
• Messages sent by an integration carry sent_via: "api_key"; the Nivox audit trail tells REST calls (api.*) from MCP calls (mcp.*).

4. Quick start

export NIVOX_API_KEY="nvx_..."          # from Integrations
BASE=https://nivox.me/api/v1

curl -s $BASE/me -H "Authorization: Bearer $NIVOX_API_KEY"                                    # who am I, what can I call
curl -s $BASE/connections -H "Authorization: Bearer $NIVOX_API_KEY"                           # my WhatsApp numbers
curl -s "$BASE/conversations?unread_only=true" -H "Authorization: Bearer $NIVOX_API_KEY"      # inbox triage
curl -s "$BASE/conversations/$CONVERSATION_ID/messages" -H "Authorization: Bearer $NIVOX_API_KEY"

# reply while window.open is true
curl -s -X POST $BASE/conversations/$CONVERSATION_ID/messages -H "Authorization: Bearer $NIVOX_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" -d '{"type":"text","text":"Oi! Já verifico para você."}'

curl -s -X POST $BASE/conversations/$CONVERSATION_ID/read -H "Authorization: Bearer $NIVOX_API_KEY" -H "Content-Type: application/json" -d '{}'

5. Endpoint reference

All paths are relative to https://nivox.me/api. Parameters marked (required) are required.

Discovery

GET /v1

Public index: name, version and the documentation, OpenAPI and MCP URLs. No key needed.

GET /v1/openapi.json

This API as an OpenAPI 3.1 document (paths, request bodies from the real tool schemas, response schemas, webhook payloads). No key needed. Import it into Postman, Insomnia or a client generator.

GET /v1/me

The calling key. Scope: any.

Response data: { api_key: { id, name, scope, role, connection_ids }, organization: { id, name }, modules: { crm, helpdesk }, mcp_endpoint, operations: [{ method, path, operation_id, mcp_tools }] }

curl -s https://nivox.me/api/v1/me -H "Authorization: Bearer $NIVOX_API_KEY"

Connections

GET /v1/connections

The WhatsApp Business numbers this key can operate. Start here.

Scope: read · MCP tool: list_connections

Response data: { connections: Connection[], scope }

curl -s https://nivox.me/api/v1/connections -H "Authorization: Bearer $NIVOX_API_KEY"

GET /v1/connections/{connection_id}/health

Latest Meta health snapshot: messaging limits, quality rating, display-name status, payment method (payment.status ok | issue), template counts, 7-day volumes and 30-day cost. Refreshed daily.

Scope: full · MCP tool: get_connection_health

Response data: { connection_id, phone, status, registered, quality_rating, health, health_checked_at }

Conversations

GET /v1/conversations

Inbox listing, most recent activity first. window.open says whether free text is allowed (24 h since the customer last wrote).

Scope: read · MCP tool: list_conversations

Response data: { conversations: Conversation[], count, next_before }

curl -s "https://nivox.me/api/v1/conversations?unread_only=true&limit=20" -H "Authorization: Bearer $NIVOX_API_KEY"

GET /v1/conversations/lookup

The conversation(s) of a phone number (digits with country code). Brazilian ninth-digit variants are matched.

Scope: read · MCP tool: find_contact

Response data: { phone, conversations: Conversation[], hint? }

curl -s "https://nivox.me/api/v1/conversations/lookup?phone=5511999998888" -H "Authorization: Bearer $NIVOX_API_KEY"

GET /v1/conversations/{conversation_id}

One conversation with its contact and 24-hour window state.

Scope: read · MCP tool: get_conversation

Response data: { conversation: Conversation, connection: { id, phone, status } }

GET /v1/conversations/{conversation_id}/messages

Message history, chronological (oldest first) within the page. Default: the latest 30. Page backwards with before; poll forward with after.

Scope: read · MCP tool: list_messages

Response data: { conversation_id, contact_name, window_open: Window, messages: Message[], count, has_more, next_before, next_after }

curl -s "https://nivox.me/api/v1/conversations/$CONVERSATION_ID/messages?limit=50" -H "Authorization: Bearer $NIVOX_API_KEY"

POST /v1/conversations/{conversation_id}/messages

Send into this conversation. Same body as POST /v1/messages (the type table below) without conversation_id, which the path fixes.

Scope: messages · MCP tool: send_text · send_template · send_media · send_buttons · send_interactive · send_reaction

Response data: see POST /v1/messages. 201 (a reaction answers 200).

curl -s -X POST https://nivox.me/api/v1/conversations/$CONVERSATION_ID/messages -H "Authorization: Bearer $NIVOX_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"type":"text","text":"Olá! Seu pedido saiu para entrega."}'

POST /v1/conversations/{conversation_id}/read

Zero the unread counter in the team inbox and send WhatsApp read receipts (blue ticks); typing: true also shows "typing…".

Scope: messages · MCP tool: mark_read

Response data: { conversation_id, unread_count, receipt_sent }

Messages

POST /v1/messages

One endpoint for every kind of send, picked by type. Free text, media, buttons, interactive messages and reactions need the 24-hour window to be open (session_expired otherwise); a template works any time and is the only way to reach a number with no conversation yet (phone, scope full).

Scope: messages · MCP tool: send_text · send_template · send_media · send_buttons · send_interactive · send_reaction

Response data: { message_id, wamid, conversation_id, status: "sent", type } (templates add template and the filled text); a reaction answers { conversation_id, wamid, emoji }. 201 (reaction 200). conversation_id may differ from the one you sent to when Meta canonicalized the number.

Send an Idempotency-Key with every send (§2.4). Delivery and read arrive later as message.status webhooks (§7) or by re-reading the messages.

curl -s -X POST https://nivox.me/api/v1/messages -H "Authorization: Bearer $NIVOX_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"type":"template","phone":"5511999998888","template_name":"order_shipped","language":"pt_BR","body_params":["4821"]}'

GET /v1/messages/search

Case-insensitive substring search over message text across the conversations this key can see.

Scope: read · MCP tool: search_messages

Response data: { messages: Message[], count }

GET /v1/messages/{message_id}/media

A 1-hour signed download URL for the image, audio, video or document of a message whose media.available is true. Download it; do not store the link.

Scope: read · MCP tool: get_media_url

Response data: { message_id, url, mime, bytes, expires_in_seconds } — 409 no_media while the file is not available.

Templates

GET /v1/templates

Message templates of a connection (cached copy of Meta’s list; the first call on a never-synced connection pulls it from Meta). Only APPROVED templates can be sent.

Scope: read · MCP tool: list_templates

Response data: { connection_id, synced_at, templates: Template[], count }

POST /v1/templates

Submit a new text template to Meta for approval (minutes to hours). Body variables are {{1}}, {{2}}… and each needs an example.

Scope: full · MCP tool: create_template

Response data: { connection_id, id, name, status } 201

POST /v1/templates/sync

Refresh the template cache of a connection from Meta (statuses, new templates).

Scope: full · MCP tool: sync_templates

Response data: { connection_id, synced, synced_at }

DELETE /v1/templates/{name}

Delete a template (every language of that name) on Meta. Irreversible.

Scope: full · MCP tool: delete_template

Response data: { connection_id, name, deleted: true }

Contacts, notes, stages and members

Needs the CRM or the Help Desk module (403 module_disabled otherwise).

GET /v1/contacts

People the organization knows (leads and clients), created automatically from WhatsApp traffic.

Scope: read · Module: CRM or Help Desk · MCP tool: list_contacts

Response data: { contacts: Contact[], count }

POST /v1/contacts

Create a contact for someone who has not written on WhatsApp yet.

Scope: messages · Module: CRM or Help Desk · MCP tool: create_contact

Response data: { contact: Contact } 201 — 409 duplicate when that WhatsApp identity already has a contact.

GET /v1/contacts/{contact_id}

Everything about one person in one call: the contact and stage, their conversations on the connections this key can see, open opportunities, open tickets and the last 10 notes.

Scope: read · Module: CRM or Help Desk · MCP tool: get_contact

Response data: { contact: Contact, conversations: [{ id, connection_id, phone, unread_count, last_message_at, window_open }], open_opportunities: Opportunity[] | null, open_tickets: Ticket[] | null, notes: Note[] } — a module that is off comes back null.

PATCH /v1/contacts/{contact_id}

Correct or enrich a contact. A name set here is never overwritten by the WhatsApp profile name.

Scope: messages · Module: CRM or Help Desk · MCP tool: update_contact

Response data: { contact: Contact }

POST /v1/contacts/{contact_id}/move

Leads: move to another stage (a won stage converts the lead). Clients: set the status.

Scope: messages · Module: CRM or Help Desk · MCP tool: move_contact

Response data: { contact: Contact }

POST /v1/contacts/{contact_id}/convert

Turn a lead into a client, or a client back into a lead.

Scope: messages · Module: CRM or Help Desk · MCP tool: convert_contact

Response data: { contact: Contact } — 409 already_in_kind when it already is that kind.

GET /v1/contacts/{contact_id}/notes

Internal notes about a contact, newest first.

Scope: read · Module: CRM or Help Desk · MCP tool: list_notes

Response data: { notes: Note[], count }

POST /v1/contacts/{contact_id}/notes

Add an internal note (never sent to WhatsApp), optionally attached to an opportunity or a ticket.

Scope: messages · Module: CRM or Help Desk · MCP tool: add_note

Response data: { note: Note } 201

GET /v1/stages

The organization’s stage vocabulary per entity, in board order. key is what every move takes; kind is open, won or lost.

Scope: read · Module: CRM or Help Desk · MCP tool: list_stages

Response data: { stages: Stage[], count }

GET /v1/members

Team members who can own a record or be assigned a ticket — id and display name only.

Scope: messages · Module: CRM or Help Desk · MCP tool: list_members

Response data: { members: [{ user_id, display_name }], count }

Opportunities

Needs the CRM module.

GET /v1/opportunities

Deals in the sales pipeline, most recently updated first.

Scope: read · Module: CRM · MCP tool: list_opportunities

Response data: { opportunities: Opportunity[], count }

POST /v1/opportunities

Open a deal for a contact.

Scope: messages · Module: CRM · MCP tool: create_opportunity

Response data: { opportunity: Opportunity } 201

GET /v1/opportunities/{opportunity_id}

One deal with its contact.

Scope: read · Module: CRM · MCP tool: get_opportunity

Response data: { opportunity: Opportunity, contact: Contact | null }

PATCH /v1/opportunities/{opportunity_id}

Change title, value, currency, expected close date or owner.

Scope: messages · Module: CRM · MCP tool: update_opportunity

Response data: { opportunity: Opportunity }

POST /v1/opportunities/{opportunity_id}/move

Advance or close a deal. A won stage stamps the close date and turns the contact into a client; lost records lost_reason.

Scope: messages · Module: CRM · MCP tool: move_opportunity

Response data: { opportunity: Opportunity, contact_converted }

Tickets

Needs the Help Desk module.

GET /v1/tickets

Support tickets, most recently updated first.

Scope: read · Module: Help Desk · MCP tool: list_tickets

Response data: { tickets: Ticket[], count }

POST /v1/tickets

Open a ticket — from a conversation (the contact is resolved for you) or for a contact.

Scope: messages · Module: Help Desk · MCP tool: create_ticket

Response data: { ticket: Ticket } 201

GET /v1/tickets/{ticket_id}

One ticket with its contact.

Scope: read · Module: Help Desk · MCP tool: get_ticket

Response data: { ticket: Ticket, contact: Contact | null }

PATCH /v1/tickets/{ticket_id}

Change subject, description, priority or the linked conversation.

Scope: messages · Module: Help Desk · MCP tool: update_ticket

Response data: { ticket: Ticket }

POST /v1/tickets/{ticket_id}/move

Move a ticket: won = resolved, lost = closed; back to an open stage clears both.

Scope: messages · Module: Help Desk · MCP tool: move_ticket

Response data: { ticket: Ticket }

POST /v1/tickets/{ticket_id}/assign

Assign a ticket to a member, or unassign it.

Scope: messages · Module: Help Desk · MCP tool: assign_ticket

Response data: { ticket: Ticket }

6. Objects

Every object has all its fields present (null rather than absent); snake_case throughout.

Connection — id, phone, verified_name, business, status (active accepts sends), registered, flow (classic · coexistence), quality_rating, health_checked_at, templates_synced_at, connected_at.

Conversation

{
  "id": "3fbb9c0a-0349-4363-a3ff-da21b273be0c",
  "connection_id": "f8a7d953-5b66-4cd8-b4e3-03168aa7add2",
  "contact_id": "79db5fd9-1fe5-4f9d-bbe2-6988253b1e71",
  "contact": { "name": "Maria Souza", "phone": "5511988887777", "wa_id": "5511988887777", "opted_out": false },
  "unread_count": 1,
  "last_message": { "preview": "Meu pedido já saiu?", "type": "text", "at": "2026-09-14T18:22:31.120Z", "direction": "inbound" },
  "window": { "open": true, "expires_at": "2026-09-15T18:22:31.120Z", "can_send_free_text": true, "last_inbound_at": "2026-09-14T18:22:31.120Z" },
  "created_at": "2026-09-01T12:00:00.000Z"
}

Message

{
  "id": "0d8f6c1e-8b7a-4c1e-9f5a-2c1d3e4f5a6b",
  "wamid": "wamid.HBgNNTUxMTk4ODg4Nzc3NxUCABIYFjNFQjBDMEI4",
  "conversation_id": "3fbb9c0a-0349-4363-a3ff-da21b273be0c",
  "direction": "inbound",
  "type": "text",
  "status": "received",
  "text": "Meu pedido já saiu?",
  "created_at": "2026-09-14T18:22:31.120Z",
  "author": "Maria Souza"
}

status: sending · sent · delivered · read · failed (outbound) · received (inbound). Optional fields: author (inbound), sent_via (user | api_key, outbound), reply_to_wamid, reactions, template, media ({ mime, bytes, status, available, filename } — download with GET /v1/messages/{message_id}/media), location, contacts, interactive, button, order (Meta's shapes), error ({ code, message } on failed sends).

Template — id, name, language, status, category, header ({ format, text, variables } or null), body ({ text, variables }), footer, buttons, components (with include_components).

Contact — id, kind (lead · client), name, name_source, phone, wa_id, email, company, tags, stage ({ key, name, kind }, leads), client_status, owner_user_id, source, stage_changed_at, converted_at, created_via/updated_via (user | api_key), created_at, updated_at.

Opportunity — id, contact_id, title, value_cents, currency, stage, owner_user_id, expected_close_on, won_at, lost_at, lost_reason, is_open, stage_changed_at, created_via, updated_via, created_at, updated_at.

Ticket — id, number, contact_id, conversation_id, subject, description, stage, priority, assignee_user_id, resolved_at, closed_at, is_open, stage_changed_at, created_via, updated_via, created_at, updated_at.

Note — id, contact_id, opportunity_id, ticket_id, body, author_via, author_user_id, created_at. Stage — key, name, entity, kind (open · won · lost), position, is_default.

7. Webhooks

Optional. Instead of polling, an organization admin registers an HTTPS endpoint on Integrations → Webhooks and Nivox POSTs signed events to it.

7.1 Setup

1. Integrations → Webhooks → New webhook: the public https:// URL (no IP addresses, no localhost or internal domains, no credentials in the URL), a description, the events, and optionally which WhatsApp connections.
2. Copy the signing secret (whsec_…) — shown once; New secret rotates it.
3. Send test delivers a webhook.test event right away and shows the HTTP status. Pause stops new events for the endpoint; Show deliveries lists the last 14 days, with Redeliver.

7.2 Events

Reactions, template status changes and CRM/Help Desk events are not webhooks in v1.

7.3 Payload

{
  "id": "5a0f4d8e-2f7b-4f6c-9d0e-1b2c3d4e5f60",
  "type": "message.received",
  "created_at": "2026-09-14T18:22:31.180Z",
  "api_version": "v1",
  "org_id": "0b8e1c7a-5d2f-4e39-9a61-3c4d5e6f7a8b",
  "data": {
    "connection": { "id": "f8a7d953-5b66-4cd8-b4e3-03168aa7add2", "phone": "+55 11 99999-0000" },
    "conversation": { "id": "3fbb9c0a-0349-4363-a3ff-da21b273be0c", "contact_id": "79db5fd9-1fe5-4f9d-bbe2-6988253b1e71", "…": "the Conversation object" },
    "message": { "id": "0d8f6c1e-8b7a-4c1e-9f5a-2c1d3e4f5a6b", "direction": "inbound", "type": "text", "status": "received", "text": "Meu pedido já saiu?", "…": "the Message object" }
  }
}

data.conversation and data.message are exactly the objects of §6. message.sent has the same data. message.status adds data.status (delivered · read · failed) and data.error ({ code, message } for failed, else null), and data.message.status is the status that fired.

7.4 Headers

7.5 Verifying the signature

Nivox signs with Standard Webhooks: the signature is base64(HMAC-SHA256(key, "{webhook-id}.{webhook-timestamp}.{raw body}")), where key is the base64-decoded part of the secret after whsec_. Verify the raw bytes you received (not re-serialized JSON) and refuse timestamps more than 5 minutes away. Libraries that do this: standardwebhooks (npm, PyPI, Go, Ruby…) and Svix.

import crypto from 'node:crypto';

export function verifyNivoxWebhook(rawBody, headers, secret) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signatures = headers['webhook-signature'] ?? '';
  if (!id || !timestamp || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = crypto.createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest('base64');
  return signatures.split(' ').some((entry) => {
    const [version, signature] = entry.split(',');
    return version === 'v1' && signature?.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  });
}

import base64, hashlib, hmac, time

def verify_nivox_webhook(raw_body: bytes, headers, secret: str) -> bool:
    msg_id, ts = headers.get("webhook-id"), headers.get("webhook-timestamp")
    if not msg_id or not ts or abs(time.time() - int(ts)) > 300:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    expected = base64.b64encode(hmac.new(key, f"{msg_id}.{ts}.".encode() + raw_body, hashlib.sha256).digest()).decode()
    return any(hmac.compare_digest(e.split(",", 1)[1], expected)
               for e in headers.get("webhook-signature", "").split() if e.startswith("v1,"))

7.6 Delivery, retries and ordering

• Answer 2xx within 10 seconds and do the work afterwards. Any other status, a timeout, a network error or a redirect (redirects are never followed — register the final URL) is a failure.
• Retries: +1 min, +5 min, +30 min, +2 h, +6 h, +12 h — 7 attempts over about 20 h 36 min; then the delivery is failed (redeliver it from Integrations). An endpoint with 10 or more consecutive failures for 3 days is disabled automatically ("Disabled after failures"; enable it again after fixing).
• At-least-once, unordered: the same event can arrive twice (deduplicate on webhook-id) and events can arrive out of order (use message.created_at and the status ranks sent < delivered < read).
• Deliveries and their payloads are kept for 14 days. Nivox resolves your hostname on every attempt and never delivers to a private address.

8. Troubleshooting

9. Changelog

• 1.0.0 (2026-09-14) — first release: 37 operations mirroring the MCP server 0.3.2, Idempotency-Key, OpenAPI 3.1, outbound webhooks (message.received, message.sent, message.status) with Standard Webhooks signatures, retries and a delivery log.