canonical: https://jentic.com/apis/nexmo.com/nexmo-external-accounts

# Nexmo External Accounts API

Jentic publishes the only available OpenAPI specification for Nexmo External Accounts API, keeping it validated and agent-ready. The External Accounts API manages the per-channel chat-app identities that Nexmo's Messages and Dispatch APIs send through - Facebook Messenger pages, Viber Service Message senders, and WhatsApp business numbers. It exposes nine endpoints for creating Messenger accounts, retrieving Viber and WhatsApp account state, updating tokens, and linking or unlinking each account to a Nexmo application so that messages routed via that application can use the right sender identity.

## For AI agents

Manage Facebook Messenger, Viber Service Message, and WhatsApp sender accounts and link them to Nexmo applications so Messages and Dispatch can use them. Nine endpoints under /beta/chatapp-accounts.

## Scope

Does not send messages, manage WhatsApp templates, or onboard new WhatsApp/Viber numbers - use only to register, retrieve, and link Messenger/Viber/WhatsApp sender accounts to Nexmo applications.

## Capabilities

- Register a Facebook Messenger sender via POST /messenger with the page-id and a long-lived page access token
- Retrieve a Messenger, Viber Service Message, or WhatsApp account by external_id via the matching GET endpoint
- Update a Messenger account's name or token via PATCH /messenger/{external_id}
- Delete a Messenger account via DELETE /messenger/{external_id}
- Link a chat-app account to a Nexmo application via POST /{provider}/{external_id}/applications
- Unlink an account from an application via DELETE /{provider}/{external_id}/applications/{application_id}
- List every chat-app account the authenticated user owns via GET /

## Use cases

### Onboarding a Messenger page for outbound chat

Before sending a Facebook Messenger message via the Messages API, the page must be registered with Nexmo. POST /messenger creates the account with the Facebook page-id and a long-lived page access token, and POST /{provider}/{external_id}/applications then links the page to a Nexmo application so messages routed through that application use it as the sender.

Example prompt: POST /messenger with the page-id and page access token, then POST /messenger/{external_id}/applications with the target Nexmo application_id.

### Token rotation for a WhatsApp or Messenger sender

Page access tokens and chat-app credentials expire. PATCH /messenger/{external_id} updates the stored token without recreating the account or relinking applications. Equivalent retrieval via GET /whatsapp/{external_id} and /viber_service_msg/{external_id} confirms the new state. The whole rotation is two HTTP calls.

Example prompt: PATCH /messenger/{external_id} with the new page access token, then GET /messenger/{external_id} to verify the updated state.

### Application-scoped chat-app provisioning by an agent

An AI agent provisioning a new application can list existing chat-app accounts, register any missing ones, and link them all to the new application in a small batch of calls. Through Jentic the agent searches by intent ('link a chat-app account to a Nexmo application'), loads the link operation schema, and executes it once per provider/external_id pair.

Example prompt: GET / to list existing accounts, then for each missing provider call POST /messenger or rely on existing Viber/WhatsApp accounts and POST /{provider}/{external_id}/applications with the target application_id.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | / | List all chat-app accounts owned by the authenticated user |
| POST | /messenger | Create a Facebook Messenger account |
| PATCH | /messenger/{external_id} | Update a Messenger account's token or name |
| DELETE | /messenger/{external_id} | Delete a Messenger account |
| GET | /whatsapp/{external_id} | Retrieve a WhatsApp account by external_id |
| POST | /{provider}/{external_id}/applications | Link a chat-app account to a Nexmo application |
| DELETE | /{provider}/{external_id}/applications/{application_id} | Unlink a chat-app account from a Nexmo application |

## Key resources

- **Account** — Top-level chat-app account record - list via GET /
- **Facebook Messenger** — Create, retrieve, update, and delete Messenger accounts via /messenger endpoints
- **Viber Service Message** — Retrieve Viber Service Message account state via GET /viber_service_msg/{external_id}
- **Whatsapp** — Retrieve WhatsApp account state via GET /whatsapp/{external_id}
- **Application** — Link and unlink chat-app accounts to Nexmo applications via /{provider}/{external_id}/applications

## Why Jentic

- **Setup:** Wiring the Nexmo External Accounts API by hand means supporting both HTTP basic and JWT bearer auth, minting per-call JWTs from your Application signing key, and routing account calls to the api.nexmo.com/beta/chatapp-accounts host. Through Jentic you install once, import the External Accounts API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** The External Accounts API puts the external account id in the URL path (/{provider}/{external_id}/...), so a rule can pin your agent to one chat-app sender account: it can read that account and link it to applications. You choose the operations it may call, so destructive ones like deleting a Messenger account or unlinking an application are not included unless you add them.
- **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 'link a chat-app account to a Nexmo application', and Jentic returns the matching operation among the endpoints with its parameter schema so the agent picks the right provider and method without browsing the reference docs.

## Related APIs

- **Nexmo Messages API** — The send-side API that uses these chat-app accounts as senders for Messenger, Viber, and WhatsApp messages
- **Nexmo Application API v2** — Manages the Nexmo applications you link chat-app accounts to
- **Twilio API** — Twilio Conversations and the Messaging Services API offer similar Messenger/WhatsApp sender management

## FAQ

### Why is there no official OpenAPI spec for Nexmo External Accounts 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 External Accounts 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 External Accounts API use?

Either HTTP basic auth (api_key/api_secret) or HTTP bearer with a JWT signed by an application's private key. Jentic stores both forms encrypted and chooses per call so the agent never handles the page access tokens or signing keys directly.

### Can I create a WhatsApp account through this API?

No. The spec exposes POST /messenger for creating Messenger accounts but only GET /whatsapp/{external_id} and GET /viber_service_msg/{external_id} for those providers. WhatsApp and Viber accounts are provisioned via the Vonage onboarding process and surface here for retrieval and application-linking only.

### What are the rate limits for the Nexmo External Accounts API?

The OpenAPI spec does not declare rate limits for the /beta/chatapp-accounts endpoints. Account-level throttles apply, and chat-app account changes are typically infrequent operations.

### How do I link a Messenger page to a Nexmo application through Jentic?

Search Jentic for 'link a chat-app account to a Nexmo application', load POST /{provider}/{external_id}/applications, and execute with provider=messenger, the page external_id, and the target application_id in the body.

### How do I rotate a Messenger page access token without losing my application links?

PATCH /messenger/{external_id} updates only the token (and name). The links created via POST /{provider}/{external_id}/applications remain intact, so messages continue routing through the same Nexmo applications.

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

Yes. Because you run Jentic One yourself, your own rules decide which of the nine operations the agent may call and which credentials it may use. Since the external account id sits in the URL path (/{provider}/{external_id}/...), you can pin the agent to a single chat-app sender: for example allow it to read that account with GET /whatsapp/{external_id} and link it via POST /{provider}/{external_id}/applications, while withholding destructive calls like DELETE /messenger/{external_id} or unlinking an application. Only the operations you grant are ever exposed to the agent.