How the API works

These five concepts explain the message path without requiring knowledge of the internal implementation.

1. A session is one connected account

The {phone} route value identifies the session carrying traffic; it is not the message recipient.

POST /v15.0/{session}/messages

• {session} is the connected account;
• to is the destination conversation;
• version preserves the HTTP contract version.

2. The token authenticates the installation

Authorization: Bearer YOUR_TOKEN

Never place tokens in query strings, logs or public examples. The interactive API lets you edit the URL and token locally.

3. One person may have multiple identity forms

The phone number is useful for display and compatibility. When available, user_id is the canonical identity. username is an optional alias.

{
  "to": "15557654321",
  "user_id": "273877414502425@lid",
  "username": "maria",
  "type": "text",
  "text": { "body": "Hello" }
}

Resolution prefers a valid user_id, then the local identity cache, then a network lookup only when needed. See Identities and contacts.

4. Request acceptance and delivery are different moments

HTTP 200 from /messages means the request was accepted. Final state arrives asynchronously in the webhook.

Moment	Observe	Meaning
accepted	HTTP response	valid payload and send started
sent	statuses[].status = sent	message published
delivered	delivered	destination device received it
read or played	read or played	recipient confirmation
failed	failed with errors[]	final error to record

Store the returned ID and correlate later status events with it.

5. Media has a source, persistence and download path

Use exactly one outgoing source: link, id or the ViperConnect base64 extension. For persisted incoming media, webhooks keep both id and url for compatibility. New consumers should prefer the ID and the API download route instead of coupling directly to a storage bucket.

HTTP client
   | authenticate, register and send
   v
ViperConnect API -> queue -> session worker -> network
   ^                                      |
   | normalized webhook                   | events and receipts
   +--------------------------------------+

Heavy work such as video preparation can run in a dedicated worker without blocking regular messages. Valkey stores state and indexes; RabbitMQ transports jobs and retries.

Core payloads follow a Cloud API-compatible shape. ViperConnect-only features are marked as extensions and do not replace the existing URL or ID contracts. Use guides to learn flows and the interactive API for exact schemas and responses.