Integration examples

Complete use cases you can run for real with an API key. All calls use the Authorization: Bearer header. See Authentication and the API Key guide to get and configure the key. Base: https://api.nuvia.ai, prefix /v1. Each case lists the required API key scopes. Grant only those when creating the key.

Case 1: Send your first message

Scopes: inboxes:read, conversations:read, messages:read, messages:create.

Discover your channels (inboxes)

List the inboxes connected to your company.

curl https://api.nuvia.ai/v1/inboxes \
  -H "Authorization: Bearer $NUVIA_API_KEY"

const res = await fetch("https://api.nuvia.ai/v1/inboxes", {
  headers: { Authorization: `Bearer ${process.env.NUVIA_API_KEY}` },
});
const { data } = await res.json();

import os, requests
res = requests.get(
    "https://api.nuvia.ai/v1/inboxes",
    headers={"Authorization": f"Bearer {os.environ['NUVIA_API_KEY']}"},
)
data = res.json()["data"]

Get a conversation

Sending a message happens inside a conversation. List conversations to get a conversationId (or create one with POST /v1/conversations).

cURL

curl "https://api.nuvia.ai/v1/conversations" \
  -H "Authorization: Bearer $NUVIA_API_KEY"

Send a text message

POST /v1/messages/send with the conversationId and the message object.

curl -X POST https://api.nuvia.ai/v1/messages/send \
  -H "Authorization: Bearer $NUVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "CONVERSATION_ID",
    "message": { "content": "Hello! Sent via API.", "contentType": "TEXT" }
  }'

await fetch("https://api.nuvia.ai/v1/messages/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUVIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    conversationId: "CONVERSATION_ID",
    message: { content: "Hello! Sent via API.", contentType: "TEXT" },
  }),
});

import os, requests
requests.post(
    "https://api.nuvia.ai/v1/messages/send",
    headers={"Authorization": f"Bearer {os.environ['NUVIA_API_KEY']}"},
    json={
        "conversationId": "CONVERSATION_ID",
        "message": {"content": "Hello! Sent via API.", "contentType": "TEXT"},
    },
)

Use contentType: "TEXT" for text messages.

Read the conversation history

GET /v1/messages/conversation/:id returns the messages; attachments are at GET /v1/messages/conversation/:id/attachments.

cURL

curl "https://api.nuvia.ai/v1/messages/conversation/CONVERSATION_ID" \
  -H "Authorization: Bearer $NUVIA_API_KEY"

Case 2: Receive events via webhooks

Register a URL of yours for Nuvia to notify in real time (messages, conversations, contacts). This case shows the end-to-end flow; the payload format, the full list of events, and the delivery guarantees are in the Webhooks guide. Scopes: to register and query, webhooks:create and webhooks:read; to manage, webhooks:update and webhooks:delete (+ messages:create if you reply automatically).

POST /v1/webhooks. There are 10 valid events: MESSAGE_SENT, MESSAGE_RECEIVED, MESSAGE_DELIVERED, MESSAGE_READ, CONVERSATION_CREATED, CONVERSATION_UPDATED, CONTACT_CREATED, CONTACT_UPDATED, FOLLOWUP_SENT, and FIELD_UPDATED. See what each one delivers in the event table.Your company has one webhook: if one is already configured, this call returns 409. Update the existing one instead of creating another.

curl -X POST https://api.nuvia.ai/v1/webhooks \
  -H "Authorization: Bearer $NUVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/nuvia/webhook",
    "events": ["MESSAGE_RECEIVED", "CONVERSATION_CREATED"],
    "status": "ACTIVE"
  }'

await fetch("https://api.nuvia.ai/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUVIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://your-server.com/nuvia/webhook",
    events: ["MESSAGE_RECEIVED", "CONVERSATION_CREATED"],
    status: "ACTIVE",
  }),
});

import os, requests
requests.post(
    "https://api.nuvia.ai/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['NUVIA_API_KEY']}"},
    json={
        "url": "https://your-server.com/nuvia/webhook",
        "events": ["MESSAGE_RECEIVED", "CONVERSATION_CREATED"],
        "status": "ACTIVE",
    },
)

Optional fields: custom_headers (for you to validate the origin) and status (ACTIVE/INACTIVE).

Receive the callbacks

When an event occurs, Nuvia makes a POST to your url, with the header X-Webhook-Event and a three-field body:

{
  "event": "MESSAGE_RECEIVED",
  "timestamp": "2026-08-13T14:03:00.000Z",
  "data": {}
}

data carries the event’s resource: the message, the conversation, or the contact, in the same format as the corresponding GET. FIELD_UPDATED is the exception and has its own structure.

Respond 2xx within 10 seconds and process in the background. There’s no retry: if your response fails or times out, the event is lost. Details in Delivery guarantees.

React to the event

From the callback, you can act via API: reply with POST /v1/messages/send (Case 1) or download attachments with GET /v1/messages/conversation/:id/attachments.

Manage the configuration

GET /v1/webhooks returns one object with the company’s configuration (or null). It’s not a list. Use that object’s id to update with PUT /v1/webhooks/:id or remove with DELETE /v1/webhooks/:id. To pause without losing the configuration, prefer PUT with status: "INACTIVE".

Case 3: Campaigns and bulk sending

Scopes: campaigns:create, campaigns:read, campaigns:update, campaigns:delete (+ messages:create for the bulk template shortcut).

Create the campaign

POST /v1/campaigns. Required fields: name, channel_type, trigger_type, and audience_config; optional ones include description, trigger_config, behavior_config, and sender_config. The internal structures of these configuration objects are in the API reference. Follow the schema there.The audience is defined at creation time, inside audience_config (via contact_ids, lists, or filters). There’s no separate enrollment step to do via API. The campaign is already born with the audience you provide here.

Check before sending

Use the previews (they create nothing): POST /v1/campaigns/audience-preview counts the audience’s contacts and POST /v1/campaigns/preview-message resolves the message variables.

Activate and track

Activate with POST /v1/campaigns/:id/activate (pause with /pause). Track with GET /v1/campaigns/:id/analytics and GET /v1/campaigns/:id/step-analytics, and export the contacts with GET /v1/campaigns/:id/enrollments/export.

cURL

curl -X POST https://api.nuvia.ai/v1/campaigns/CAMPAIGN_ID/activate \
  -H "Authorization: Bearer $NUVIA_API_KEY"

Shortcut: to send a WhatsApp template to several contacts without building a campaign, use POST /v1/messages/send-bulk-template (scope messages:create). The step-by-step, with the template parameters and Meta’s limits, is in the guide Bulk template sending on WhatsApp.

Case 4: Sync contacts

Keep your external CRM and Nuvia in sync. Scopes: contacts:read, contacts:create, contacts:update, contacts:delete.

Check for duplicates by phone

Before creating, resolve the phone numbers to see which already exist: POST /v1/contacts/find-by-phones.

curl -X POST https://api.nuvia.ai/v1/contacts/find-by-phones \
  -H "Authorization: Bearer $NUVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phones": ["+5511999999999", "+5511888888888"] }'

const res = await fetch("https://api.nuvia.ai/v1/contacts/find-by-phones", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUVIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phones: ["+5511999999999", "+5511888888888"] }),
});

import os, requests
res = requests.post(
    "https://api.nuvia.ai/v1/contacts/find-by-phones",
    headers={"Authorization": f"Bearer {os.environ['NUVIA_API_KEY']}"},
    json={"phones": ["+5511999999999", "+5511888888888"]},
)

Create the missing contacts

POST /v1/contacts. Fields: firstname, lastname, phone, email, company, and properties.

curl -X POST https://api.nuvia.ai/v1/contacts \
  -H "Authorization: Bearer $NUVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "Mary",
    "lastname": "Smith",
    "phone": "+5511999999999",
    "email": "mary@company.com"
  }'

await fetch("https://api.nuvia.ai/v1/contacts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUVIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    firstname: "Mary",
    lastname: "Smith",
    phone: "+5511999999999",
    email: "mary@company.com",
  }),
});

import os, requests
requests.post(
    "https://api.nuvia.ai/v1/contacts",
    headers={"Authorization": f"Bearer {os.environ['NUVIA_API_KEY']}"},
    json={
        "firstname": "Mary",
        "lastname": "Smith",
        "phone": "+5511999999999",
        "email": "mary@company.com",
    },
)

Update and list

Update a contact with PUT /v1/contacts/:id (or just the name with PUT /v1/contacts/:id/name) and list/paginate with GET /v1/contacts. To remove the link between a contact and an external CRM, use DELETE /v1/contacts/:id/crm-link: this only undoes the link; the contact keeps existing in Nuvia (it’s not a contact deletion).

Other public surfaces

Consumable via API key and covered in the Reference: Agents, Tables and lists, Conversations, and Knowledge base. See the map in API sections.

Getting started

Guides

Integration examples

Case 1: Send your first message

Case 2: Receive events via webhooks

Case 3: Campaigns and bulk sending

Case 4: Sync contacts

Other public surfaces

Next steps

API Key guide

API reference

​Case 1: Send your first message

​Case 2: Receive events via webhooks

​Case 3: Campaigns and bulk sending

​Case 4: Sync contacts

​Other public surfaces

​Next steps

API Key guide

API reference

Case 1: Send your first message

Case 2: Receive events via webhooks

Case 3: Campaigns and bulk sending

Case 4: Sync contacts

Other public surfaces

Next steps