canonical: https://jentic.com/apis/nexmo.com/nexmo-messages-olympus

# Nexmo Messages API

Jentic publishes the only available OpenAPI specification for Nexmo Messages API, keeping it validated and agent-ready. This messages-olympus slug indexes the same Messages 1.4.0 service exposed at `/v1/messages` - a single POST / endpoint that sends a message over SMS, MMS, WhatsApp, Viber Service Message, or Facebook Messenger based on the channel field in the request body. The slug name reflects an internal Vonage codename and is functionally identical to the messages-api slug.

## For AI agents

Send a message over SMS, MMS, WhatsApp, Viber Service Message, or Facebook Messenger from a single POST endpoint. The channel is selected by the request body.

## Scope

Does not orchestrate failover across channels, register chat-app sender accounts, or surface inbound message webhooks - use only for sending a single message on one of the supported channels.

## Capabilities

- Send an SMS via POST / with channel=sms and text content
- Send a WhatsApp text or template message via channel=whatsapp
- Send a Viber Service Message via channel=viber_service
- Send a Facebook Messenger message via channel=messenger
- Send rich content (image, audio, video, file) by setting message_type appropriately
- Authenticate with either basic auth or an application-scoped JWT bearer token

## Use cases

### Unified transactional notifications

Instead of integrating SMS, WhatsApp, Messenger, and Viber separately, applications send through one POST /. The channel field selects the path; the rest of the body carries to, from, and a message_type-shaped payload. Delivery webhooks for every channel arrive on the same application callback URL.

Example prompt: POST / with channel=sms, message_type=text, recipient in to, sender id in from, and message body in text.

### WhatsApp template campaigns

Marketing teams send opt-in WhatsApp campaigns by submitting pre-approved templates through POST / with channel=whatsapp and message_type=template. The same endpoint returns a message_uuid, and read and delivery events fan out to the configured webhook for downstream analytics.

Example prompt: POST / with channel=whatsapp, message_type=template, and a template object holding name, namespace, and parameter array.

### Single-call cross-channel send by an AI agent

An agent reaches a user without picking a channel ahead of time: through Jentic the agent searches once for 'send a message via nexmo', loads POST /, and executes with whichever channel the user is reachable on. The agent never owns retry timers, signing keys, or per-channel client code.

Example prompt: Search Jentic for 'send a message via nexmo', load POST /, and execute with channel chosen by the user's contact preference.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/` | Send a message on the channel specified in the request body |

## Key resources

- **Message** — Unified send resource - POST / with channel-specific fields

## Why Jentic

- **Setup:** Wiring the Nexmo Messages API by hand means supporting both HTTP basic and JWT bearer auth, minting per-call JWTs from your Application signing key, and posting to the api.nexmo.com/v1/messages host with the correct channel-specific body. Through Jentic you install once, import the Messages API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** The Messages API exposes a single send endpoint and carries the channel and recipient in the request body, so scoping is by operation rather than by resource: limit the agent to the operation it needs, which is sending a single message on a supported channel. That send call is the only thing it can run.
- **Credential handling:** Your Nexmo basic credentials and Application signing key are stored once, encrypted, by your own Jentic One instance and used to mint per-call JWTs at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send a message via Nexmo', and Jentic returns the POST / operation with its full request schema, including each channel's message_type variants, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Nexmo External Accounts API** — Manages the Messenger, Viber, and WhatsApp sender accounts used by Messages
- **Nexmo Dispatch API** — Wraps Messages with multi-channel failover workflows
- **Twilio API** — Twilio Programmable Messaging covers SMS, WhatsApp, and Messenger as a competing unified send

## FAQ

### Why is there no official OpenAPI spec for Nexmo Messages API?

Vonage (formerly Nexmo) does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Nexmo Messages API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Nexmo Messages API use?

Either HTTP basic auth (api_key/api_secret) or HTTP bearer with an application-scoped JWT. WhatsApp, Viber Service Message, and Messenger require the JWT path because those channels are tied to a Nexmo application.

### Can I send template-based WhatsApp messages with this slug?

Yes. POST / with channel=whatsapp and message_type=template accepts a template object with name, namespace, and parameters. The 202 response carries a message_uuid for status correlation.

### What are the rate limits for the Nexmo Messages API?

The OpenAPI spec does not declare rate limits. Channel-specific quotas apply: WhatsApp business tiers, Messenger policy windows, and SMS carrier throughput. The exact figures live on developer.nexmo.com per channel.

### How do I send a Messenger image through Jentic?

Search Jentic for 'send a message via nexmo', load POST /, and execute with channel=messenger, message_type=image, the user's PSID in to, the page id in from, and an image url in the body.

### How does messages-olympus differ from the messages-api slug?

Both indexes point at the same Messages 1.4.0 service at `/v1/messages` with the same single POST / endpoint. The messages-olympus name reflects an internal Vonage codename; either slug resolves to the same operation.

### Can I limit what my agent is allowed to do with the Nexmo Messages API?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use. The Nexmo Messages API exposes a single send endpoint (POST /), so you scope by operation: grant the agent only that one send call and nothing else. You can also restrict which stored Nexmo basic or JWT credentials it may use, keeping the channel and recipient it sends to within bounds you set.