External Accounts API

The External Accounts API is used to manage accounts for Viber Business Messages, Facebook Messenger and Whatsapp for use in the Messages and Dispatch APIs.

Download OpenAPI Specification

Application

Inbound messages to an external account which is linked to an application will be delivered to the application's inbound URL.

Available Operations

Link application to an account

posthttps://api.nexmo.com/beta/chatapp-accounts/:provider/:external_id/applications

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

provider

string

Required

Provider of the account you want to assign an application to

Must be one of:messengerviber_service_msgwhatsapprcs

external_id

string

Required

External id of the account you want to assign an application to. This is channel dependent. For Facebook it will be your Facebook Page ID, for Viber your Viber Service Message ID and for WhatsApp your WhatsApp number, for RCS it will be the RCS Agent ID.

Request Body
Content Type
application/json

application

string

Required

example78d335fa-323d-0114-9c3d-d6f0d48968cf

There is just one application allowed per an account. The application type must be type "messages". For more information please see Application API Spec

Example Request

Responses
Content Type
application/json

OK.

name

string

examplename

The account name

applications

array

The array of associated application ids

external_id

string

Required

example12345678

The external identifier for this account

api_key

string

Required

exampleabcd1234

The external api key for this account

provider

string

Required

examplemessenger

The provider (will be one of messenger, viber_service_msg, whatsapp, rcs).

Must be one of:messengerviber_service_msgwhatsapprcs

access_token

string

exampleaccessToken

The provider access token (only for messenger)

Example Response

Unlink application from an account

deletehttps://api.nexmo.com/beta/chatapp-accounts/:provider/:external_id/applications/:application_id

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

provider

string

Required

Provider of the account you want to unlink an application from

Must be one of:messengerviber_service_msgwhatsapprcs

external_id

string

Required

External id of the account you want to unlink an application from

application_id

string

Required

Id of the application you want to unlink

Responses

No Content.

Account

An external-account used as the from field in the Messages API and Dispatch API

Available Operations

Retrieve all accounts you own

Retrieve all accounts you own

gethttps://api.nexmo.com/beta/chatapp-accounts/

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Query Parameters

provider

string

Filter by provider

Must be one of:messengerviber_service_msgwhatsapp

page_number

integer

Default1

example1

Page number of the results

page_size

integer

Default20

example1

Page size of the results

Responses
Content Type
application/json

OK.

page_number

integer

example1

page_size

integer

example10

_embedded

array

name

string

exampleoptionalName

The account name

applications

array

The array of associated application ids

external_id

string

Required

example12345678

The external identifier for this account

api_key

string

Required

exampleabcd1234

The external api key for this account

provider

string

Required

examplewhatsapp

The provider (will be whatsapp).

access_token

string

Required

examplemyAccessToken

The provider access token

_links

object

self

object

href

string

examplehttps://api.nexmo.com/beta/chatapp-accounts?page_number=1&page_size=10

object

href

string

examplehttps://api.nexmo.com/beta/chatapp-accounts?page_number=3&page_size=10

object

href

string

examplehttps://api.nexmo.com/beta/chatapp-accounts?page_number=1&page_size=10

first

object

href

string

examplehttps://api.nexmo.com/beta/chatapp-accounts?page_number=1&page_size=10

last

object

href

string

examplehttps://api.nexmo.com/beta/chatapp-accounts?page_number=4&page_size=10

Example Response

Facebook Messenger

Managing your Facebook Messenger account

Available Operations

Create a Messenger account

posthttps://api.nexmo.com/beta/chatapp-accounts/messenger

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Request Body
Content Type
application/json

external_id

string

Required

example12345678

This is the unique identifier within the provider's domain. In this case it is the Page ID for your Facebook Page. Go to your Facebook Page, click "Settings", click "Messenger platform " scroll down to "Messenger link" to find your Page ID.

access_token

string

Required

examplemyAccessToken

This is the Facebook Business Page token. You can obtain the token using one of the following methods:

Linking your Facebook Business Page to your account with our Dashboard tool
Requesting a Page Access Token using the steps in the Facebook token reference

name

string

exampleoptionalName

Custom account name

applications

array

Contains a list of application IDs which are linked to the account.

There is just one application allowed per an account.
The application type must be type "messages".

For more information see Application API spec

Example Request

Responses
Content Type
application/json

Created.

name

string

exampleoptionalName

The account name

applications

array

The array of associated application ids

external_id

string

Required

example12345678

The external identifier for this account

api_key

string

Required

exampleabcd1234

The external api key for this account

provider

string

Required

examplemessenger

The provider (will be messenger).

access_token

string

Required

examplemyAccessToken

The provider access token

Example Response

Retrieve a Messenger account

gethttps://api.nexmo.com/beta/chatapp-accounts/messenger/:external_id

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

external_id

string

Required

External id of the account you want to retrieve. In this case it is the Facebook Page ID.

Responses
Content Type
application/json

OK.

name

string

exampleoptionalName

The account name

applications

array

The array of associated application ids

external_id

string

Required

example12345678

The external identifier for this account

api_key

string

Required

exampleabcd1234

The external api key for this account

provider

string

Required

examplemessenger

The provider (will be messenger).

access_token

string

Required

examplemyAccessToken

The provider access token

Example Response

Update a Messenger account

patchhttps://api.nexmo.com/beta/chatapp-accounts/messenger/:external_id

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

external_id

string

Required

External id of the account you want to update. In this case it is the Facebook Page ID.

Request Body
Content Type
application/json

name

string

examplenewName

The new account name

applications

array

access_token

string

exampleupdatedAccessToken

Example Request

Responses
Content Type
application/json

OK.

name

string

examplenewName

The account name

applications

array

The array of associated application ids

external_id

string

Required

example12345678

The external identifier for this account. In this case it is the Facebook Page ID.

api_key

string

Required

exampleabcd1234

The external api key for this account

provider

string

Required

examplemessenger

The provider (will be messenger).

access_token

string

Required

exampleupdatedAccessToken

The provider access token

Example Response

Delete a Messenger account

deletehttps://api.nexmo.com/beta/chatapp-accounts/messenger/:external_id

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

external_id

string

Required

External id of the account you want to delete. In this case it is the Facebook Page ID.

Responses

No Content.

Viber Service Message

Managing your Viber Service Message account

Available Operations

Retrieve a Viber Service Message account

Retrieve a Viber Service Message account

gethttps://api.nexmo.com/beta/chatapp-accounts/viber_service_msg/:external_id

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

external_id

string

Required

External id of the account you want to retrieve. In this case it will be your Viber Service Message ID.

Responses
Content Type
application/json

OK.

name

string

exampleoptionalName

The account name

applications

array

The array of associated application ids

external_id

string

Required

example12345678

The external identifier for this account

api_key

string

Required

exampleabcd1234

The external api key for this account

provider

string

Required

exampleviber_service_msg

The provider (will be viber_service_msg).

Example Response

Managing your Whatsapp account

Available Operations

Retrieve a Whatsapp account

Retrieve a Whatsapp account

gethttps://api.nexmo.com/beta/chatapp-accounts/whatsapp/:external_id

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Path Parameters

external_id

string

Required

External id of the account you want to retrieve. In this case it will be the WhatsApp number.

Responses
Content Type
application/json

OK.

name

string

exampleoptionalName

The account name

applications

array

The array of associated application ids

external_id

string

Required

example12345678

The external identifier for this account

api_key

string

Required

exampleabcd1234

The external api key for this account

provider

string

Required

examplewhatsapp

The provider (will be whatsapp).

External Accounts API

Application

Available Operations

Link application to an account

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Unlink application from an account

Authentication

Path Parameters

Responses

Account

Available Operations

Retrieve all accounts you own

Authentication

Query Parameters

Responses Content Typeapplication/json

Example Response

Facebook Messenger

Available Operations

Create a Messenger account

Authentication

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Retrieve a Messenger account

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Update a Messenger account

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Delete a Messenger account

Authentication

Path Parameters

Responses

Viber Service Message

Available Operations

Retrieve a Viber Service Message account

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Whatsapp

Available Operations

Retrieve a Whatsapp account

Authentication

Path Parameters

Responses Content Typeapplication/json

Example Response

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json

Responses
Content Type
application/json