External Accounts Developer Preview

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.

Download OpenAPI 3 Definition

Application

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

Link application to an account

POST https://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 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

Path Parameters

Key Description Example Default
provider
Required | string

Provider of the account you want to assign an application to


Must be one of: messenger, viber_service_msg or whatsapp
None None
external_id
Required | string

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.

None None

Request body application/json

Key Description Example Default
application
Required | string

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

applicationId None

View response field descriptions

Response Fields

Field Description
name

The account name

applications
array of strings

The array of associated application ids

external_id

The external identifier for this account

api_key

The external api key for this account

provider

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

One of: messenger, viber_service_msg or whatsapp
access_token

The provider access token (only for messenger)

{
  "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"
}

Unlink application from an account

DELETE https://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 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

Path Parameters

Key Description Example Default
provider
Required | string

Provider of the account you want to unlink an application from


Must be one of: messenger, viber_service_msg or whatsapp
None None
external_id
Required | string

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

None None
application_id
Required | string

Id of the application you want to unlink

None None
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"
}

Account

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

Retrieve all accounts you own

GET https://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 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

Query Parameter

Key Description Example Default
provider
string

Filter by provider


Must be one of: messenger, viber_service_msg or whatsapp
None None
page_number
integer

Page number of the results

1 1
page_size
integer

Page size of the results

1 20

View response field descriptions

Response Fields

Field Description
page_number
page_size
_embedded
array of s
{
  "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"
}

Facebook Messenger

Managing your [Facebook Messenger](https://developer.nexmo.com/messages/concepts/facebook) account

Create a Messenger account

POST https://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 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

Request body application/json

Key Description Example Default
external_id
Required | string

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.

12345678 None
access_token
Required | string

It is a Facebook Page token. There ways how to obtain the token

myAccessToken None
name
string

Custom account name

optionalName None
applications
array
of string's
None

View response field descriptions

Response Fields

Field Description
name

The account name

applications
array of strings

The array of associated application ids

external_id

The external identifier for this account

api_key

The external api key for this account

provider

The provider (will be messenger).

access_token

The provider access token

{
  "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"
}

Retrieve a Messenger account

GET https://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 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

Path Parameters

Key Description Example Default
external_id
Required | string

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

None None

View response field descriptions

Response Fields

Field Description
name

The account name

applications
array of strings

The array of associated application ids

external_id

The external identifier for this account

api_key

The external api key for this account

provider

The provider (will be messenger).

access_token

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"
}
No content

Update a Messenger account

PATCH https://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 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

Path Parameters

Key Description Example Default
external_id
Required | string

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

None None

Request body application/json

Key Description Example Default
name
string

The new account name

newName None
applications
array
of string's
None
access_token
string

None

updatedAccessToken None

View response field descriptions

Response Fields

Field Description
name

The account name

applications
array of strings

The array of associated application ids

external_id

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

api_key

The external api key for this account

provider

The provider (will be messenger).

access_token

The provider access token

{
  "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"
}
No content

Delete a Messenger account

DELETE https://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 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

Path Parameters

Key Description Example Default
external_id
Required | string

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

None None
No content
{
  "title": "Unauthorised",
  "detail": "Request header 'Authorization' missing / Invalid Token"
}
{
  "title": "Wrong authentication - You are not authorised to access this resource"
}
No content

Viber Service Message

Managing your [Viber Service Message](https://developer.nexmo.com/messages/concepts/viber) account

Retrieve a Viber Service Message account

GET https://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 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

Path Parameters

Key Description Example Default
external_id
Required | string

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

None None

View response field descriptions

Response Fields

Field Description
name

The account name

applications
array of strings

The array of associated application ids

external_id

The external identifier for this account

api_key

The external api key for this account

provider

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"
}
No content

Whatsapp

Managing your [Whatsapp](https://developer.nexmo.com/messages/concepts/whatsapp) account

Retrieve a Whatsapp account

GET https://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 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

Path Parameters

Key Description Example Default
external_id
Required | string

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

None None

View response field descriptions

Response Fields

Field Description
name

The account name

applications
array of strings

The array of associated application ids

external_id

The external identifier for this account

api_key

The external api key for this account

provider

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"
}
No content