The External Accounts API is used to manage accounts for Viber Service Messages, Facebook Messenger and Whatsapp for use in the Messages and Dispatch APIs.
Inbound messages to an external account which is linked to an application will be delivered to the application's inbound URL.
An external-account used as the from
field in the Messages API and Dispatch API
Managing your Facebook Messenger account
Managing your Viber Service Message account
Managing your Whatsapp account
Inbound messages to an external account which is linked to an application will be delivered to the application's inbound URL.
POST
https://api.nexmo.com/beta/chatapp-accounts/:provider/:external_id/applications
Host
https://api.nexmo.com
POST
/beta/chatapp-accounts/:provider/:external_id/applications
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 | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
Provider of the account you want to assign an application to
Must be one of:messenger
, viber_service_msg
or whatsapp
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.
Request body can contain any of the following. Please note, the only one application can be linked to the account.
There is just one application allowed per an account. The application type must be type "messages". For more information please see Application API Spec
The account name
The array of associated application ids
The external identifier for this account
The external api key for this account
The provider (will be one of messenger, viber_service_msg, whatsapp
).
messenger
, viber_service_msg
or whatsapp
The provider access token (only for messenger
)
{
"application": "applicationId"
}
{
"name": "name",
"applications": [
"applicationId"
],
"external_id": "12345678",
"api_key": "abcd1234",
"provider": "messenger",
"access_token": "accessToken"
}
{
"title": "Unauthorised",
"detail": "Request header 'Authorization' missing / Invalid Token"
}
{
"type": "https://www.nexmo.com/messages/Errors#Forbidden",
"title": "Forbidden",
"detail": "Cannot link application"
}
{
"type": "https://www.nexmo.com/messages/Errors#Conflict",
"title": "Application conflict",
"detail": "Unable to link application"
}
DELETE
https://api.nexmo.com/beta/chatapp-accounts/:provider/:external_id/applications/:application_id
Host
https://api.nexmo.com
DELETE
/beta/chatapp-accounts/:provider/:external_id/applications/:application_id
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 | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
Provider of the account you want to unlink an application from
Must be one of:messenger
, viber_service_msg
or whatsapp
External id of the account you want to unlink an application from
Id of the application you want to unlink
No Content.
{
"title": "Unauthorised",
"detail": "Request header 'Authorization' missing / Invalid Token"
}
{
"type": "https://www.nexmo.com/messages/Errors#Forbidden",
"title": "Forbidden",
"detail": "Cannot unlink application"
}
{
"type": "https://www.nexmo.com/messages/Errors#Conflict",
"title": "Application conflict",
"detail": "Unable to unlink application"
}
An external-account used as the from
field in the Messages API and Dispatch API
GET
https://api.nexmo.com/beta/chatapp-accounts
Host
https://api.nexmo.com
GET
/beta/chatapp-accounts
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 | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
Filter by provider
Must be one of:messenger
, viber_service_msg
or whatsapp
Page number of the results
Page size of the results
{
"page_number": 1,
"page_size": 10,
"_embedded": [
{
"name": "optionalName",
"applications": [
"optionalApplicationId"
],
"external_id": "12345678",
"api_key": "abcd1234",
"provider": "whatsapp",
"access_token": "myAccessToken"
}
],
"_links": {
"self": {
"href": "https://api.nexmo.com/beta/chatapp-accounts?page_number=1&page_size=10"
},
"next": {
"href": "https://api.nexmo.com/beta/chatapp-accounts?page_number=3&page_size=10"
},
"prev": {
"href": "https://api.nexmo.com/beta/chatapp-accounts?page_number=1&page_size=10"
},
"first": {
"href": "https://api.nexmo.com/beta/chatapp-accounts?page_number=1&page_size=10"
},
"last": {
"href": "https://api.nexmo.com/beta/chatapp-accounts?page_number=4&page_size=10"
}
}
}
{
"title": "Unauthorised",
"detail": "Request header 'Authorization' missing / Invalid Token"
}
Managing your Facebook Messenger account
POST
https://api.nexmo.com/beta/chatapp-accounts/messenger
Host
https://api.nexmo.com
POST
/beta/chatapp-accounts/messenger
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 | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
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.
This is the Facebook Business Page token. You can obtain the token using one of the following methods:
Custom account name
Contains a list of application IDs which are linked to the account.
The account name
The array of associated application ids
The external identifier for this account
The external api key for this account
The provider (will be messenger
).
The provider access token
{
"external_id": "12345678",
"access_token": "myAccessToken"
}
{
"external_id": "12345678",
"access_token": "myAccessToken",
"name": "optionalName",
"applications": [
"optionalApplicationId"
]
}
{
"name": "optionalName",
"applications": [
"optionalApplicationId"
],
"external_id": "12345678",
"api_key": "abcd1234",
"provider": "messenger",
"access_token": "myAccessToken"
}
{
"type": "https://www.nexmo.com/messages/Errors#InvalidParams",
"title": "Your request parameters didn't validate.",
"detail": "Found errors validating 1 of your submitted parameters.",
"instance": "abc123",
"invalid_params": [
{
"name": "external_id",
"reason": "Missing `external_id` field"
}
]
}
{
"title": "Unauthorised",
"detail": "Request header 'Authorization' missing / Invalid Token"
}
{
"title": "Wrong authentication - You are not authorised to access this resource"
}
GET
https://api.nexmo.com/beta/chatapp-accounts/messenger/:external_id
Host
https://api.nexmo.com
GET
/beta/chatapp-accounts/messenger/:external_id
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 | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
External id of the account you want to retrieve. In this case it is the Facebook Page ID.
The account name
The array of associated application ids
The external identifier for this account
The external api key for this account
The provider (will be messenger
).
The provider access token
{
"name": "optionalName",
"applications": [
"optionalApplicationId"
],
"external_id": "12345678",
"api_key": "abcd1234",
"provider": "messenger",
"access_token": "myAccessToken"
}
{
"title": "Unauthorised",
"detail": "Request header 'Authorization' missing / Invalid Token"
}
This endpoint does not support application/json
PATCH
https://api.nexmo.com/beta/chatapp-accounts/messenger/:external_id
Host
https://api.nexmo.com
PATCH
/beta/chatapp-accounts/messenger/:external_id
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 | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
External id of the account you want to update. In this case it is the Facebook Page ID.
Request body can contain any of the following
The new account name
The account name
The array of associated application ids
The external identifier for this account. In this case it is the Facebook Page ID.
The external api key for this account
The provider (will be messenger
).
The provider access token
{
"name": "newName",
"applications": [
"newApplicationId"
],
"access_token": "updatedAccessToken"
}
{
"name": "newName",
"applications": [
"newApplicationId"
],
"external_id": "12345678",
"api_key": "abcd1234",
"provider": "messenger",
"access_token": "updatedAccessToken"
}
{
"type": "https://www.nexmo.com/messages/Errors#InvalidParams",
"title": "Your request parameters didn't validate.",
"detail": "Found errors validating 1 of your submitted parameters.",
"instance": "abc123",
"invalid_params": [
{
"name": "external_id",
"reason": "'external_id' parameter cannot be changed"
}
]
}
{
"title": "Unauthorised",
"detail": "Request header 'Authorization' missing / Invalid Token"
}
{
"title": "Wrong authentication - You are not authorised to access this resource"
}
This endpoint does not support application/json
DELETE
https://api.nexmo.com/beta/chatapp-accounts/messenger/:external_id
Host
https://api.nexmo.com
DELETE
/beta/chatapp-accounts/messenger/:external_id
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 | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
External id of the account you want to delete. In this case it is the Facebook Page ID.
No Content.
{
"title": "Unauthorised",
"detail": "Request header 'Authorization' missing / Invalid Token"
}
{
"title": "Wrong authentication - You are not authorised to access this resource"
}
This endpoint does not support application/json
GET
https://api.nexmo.com/beta/chatapp-accounts/viber_service_msg/:external_id
Host
https://api.nexmo.com
GET
/beta/chatapp-accounts/viber_service_msg/:external_id
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 | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
External id of the account you want to retrieve. In this case it will be your Viber Service Message ID.
The account name
The array of associated application ids
The external identifier for this account
The external api key for this account
The provider (will be viber_service_msg
).
{
"name": "optionalName",
"applications": [
"optionalApplicationId"
],
"external_id": "12345678",
"api_key": "abcd1234",
"provider": "viber_service_msg"
}
{
"title": "Unauthorised",
"detail": "Request header 'Authorization' missing / Invalid Token"
}
This endpoint does not support application/json
GET
https://api.nexmo.com/beta/chatapp-accounts/whatsapp/:external_id
Host
https://api.nexmo.com
GET
/beta/chatapp-accounts/whatsapp/:external_id
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 | Example | Default |
---|---|---|---|
Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
External id of the account you want to retrieve. In this case it will be the WhatsApp number.
The account name
The array of associated application ids
The external identifier for this account
The external api key for this account
The provider (will be whatsapp
).
{
"name": "optionalName",
"applications": [
"optionalApplicationId"
],
"external_id": "12345678",
"api_key": "abcd1234",
"provider": "whatsapp"
}
{
"title": "Unauthorised",
"detail": "Request header 'Authorization' missing / Invalid Token"
}
This endpoint does not support application/json