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

# Nexmo External Accounts API

Jentic publishes the only available OpenAPI specification for Nexmo External Accounts API, keeping it validated and agent-ready. This external-accounts-api slug is the alternate-named copy of Nexmo's chat-app account service. It exposes the same nine endpoints under /beta/chatapp-accounts for managing Facebook Messenger, Viber Service Message, and WhatsApp sender identities, plus the link/unlink operations that bind those identities to a Nexmo application so the Messages and Dispatch APIs route through the right sender.

## For AI agents

Manage Facebook Messenger, Viber Service Message, and WhatsApp sender accounts and link them to Nexmo applications. 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

- List all chat-app accounts owned by the authenticated user via GET /
- Create a Facebook Messenger sender via POST /messenger
- Retrieve Messenger, Viber Service Message, or WhatsApp account state via the matching GET endpoint
- Update a Messenger account's token via PATCH /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}

## Use cases

### Provisioning chat-app senders for a new Nexmo application

When a team spins up a new Nexmo application, they need to register or relink the chat-app accounts that will act as senders. POST /messenger registers a Messenger page; POST /{provider}/{external_id}/applications then links Messenger, Viber, or WhatsApp accounts to the application_id. The whole flow is a handful of calls.

Example prompt: POST /messenger to create the Messenger account, then POST /messenger/{external_id}/applications with application_id to bind it to the new Nexmo application.

### Migrating chat-app senders between applications

When applications are split or merged, chat-app senders need to be unlinked from one application and linked to another. DELETE /{provider}/{external_id}/applications/{application_id} removes the old binding; POST /{provider}/{external_id}/applications creates the new one. Account state itself is preserved across the migration.

Example prompt: DELETE /messenger/{external_id}/applications/{old_app_id}, then POST /messenger/{external_id}/applications with the new application_id.

### Agent-driven inventory and audit of chat-app accounts

An AI agent auditing a Nexmo tenant can list all chat-app accounts, fetch each account's full state, and check which applications they link to. Through Jentic the agent searches once for 'list chat-app accounts on nexmo' and walks through the GET endpoints without needing to hand-build base URL paths.

Example prompt: GET / to list all accounts, then for each account fetch GET /messenger/{external_id} or /whatsapp/{external_id} as appropriate to capture the linked applications.

## Key endpoints

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

## Key resources

- **Account** — Top-level chat-app account record - list via GET /
- **Facebook Messenger** — Create, retrieve, update, 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

## 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** — Sends Messenger, Viber, and WhatsApp messages through the senders managed here
- **Nexmo Application API v2** — Manages the applications you bind chat-app accounts to
- **Twilio API** — Twilio Conversations and Messaging Services cover similar sender management for Messenger and WhatsApp

## 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 injects them at execution time so the agent does not see Facebook page tokens or signing keys.

### Can I create WhatsApp or Viber accounts via this API?

No. Only POST /messenger creates new accounts. WhatsApp and Viber Service Message senders are provisioned via Vonage onboarding and surface here through GET /whatsapp/{external_id} and GET /viber_service_msg/{external_id} for retrieval and application-linking.

### 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. Limits are imposed at account level by Vonage and these provisioning operations are typically very low frequency.

### How do I link a chat-app account 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, external_id, and the target application_id.

### How does this external-accounts-api slug differ from the external-accounts slug?

Both slugs index the same underlying API at /beta/chatapp-accounts with the same nine endpoints. The duplication exists from the original spec ingest; either slug resolves to the same operations.

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

Yes. Because Jentic One is self-hosted by you, your own rules decide which operations and credentials the agent may use with the Nexmo External Accounts API. Since the API carries the external account id in the URL path (/{provider}/{external_id}/...), you can pin the agent to a single chat-app sender account and let it only read that account (GET /messenger/{external_id}, GET /whatsapp/{external_id}) and link it to applications (POST /{provider}/{external_id}/applications). Destructive operations such as deleting a Messenger account (DELETE /messenger/{external_id}) or unlinking an application are excluded unless you explicitly add them to the agent's allowed operations.