Skip to navigation
Application Account Facebook Messenger Viber Service Message WhatsApp
 
 

External Accounts API

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 OAS 3 Definition
Improve this specification

Jump to:

Application »

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

Account »

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

Facebook Messenger »

Managing your Facebook Messenger account

Viber Service Message »

Managing your Viber Service Message account

Whatsapp »

Managing your Whatsapp account

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

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

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

provider
string | Required

Provider of the account you want to assign an application to

Must be one of: messenger, viber_service_msg or whatsapp
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.

Request body application/json

Request body can contain any of the following. Please note, the only one application can be linked to the account.

application
string | Required

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

Responses

200 OK.
name
string

The account name

applications
array of strings

The array of associated application ids

external_id
string

The external identifier for this account

api_key
string

The external api key for this account

provider
string

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

One of: messenger, viber_service_msg or whatsapp
access_token
string

The provider access token (only for messenger)

Example Request

{
  "application": "applicationId"
}

Example Responses

200 401 403 409 
{
  "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
Host https://api.nexmo.com
DELETE /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

provider
string | Required

Provider of the account you want to unlink an application from

Must be one of: messenger, viber_service_msg or whatsapp
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

Example Responses

204 401 403 409 
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

Available Operations:

Retrieve all accounts you own

GET https://api.nexmo.com/beta/chatapp-accounts
Host https://api.nexmo.com
GET /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

provider
string

Filter by provider

Must be one of: messenger, viber_service_msg or whatsapp
page_number
integer | Default: 1

Page number of the results

page_size
integer | Default: 20

Page size of the results

Responses

200 OK.
page_number
integer
page_size
integer
_embedded
array

Example Responses

200 401 
{
  "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 account

Available Operations:

Create a Messenger account

POST https://api.nexmo.com/beta/chatapp-accounts/messenger
Host https://api.nexmo.com
POST /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

external_id
string | Required

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

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

name
string

Custom account name

applications
array of strings

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

Responses

201 Created.
name
string

The account name

applications
array of strings

The array of associated application ids

external_id
string

The external identifier for this account

api_key
string

The external api key for this account

provider
string

The provider (will be messenger).

access_token
string

The provider access token

Example Request

{
  "external_id": "12345678",
  "access_token": "myAccessToken"
}
{
  "external_id": "12345678",
  "access_token": "myAccessToken",
  "name": "optionalName",
  "applications": [
    "optionalApplicationId"
  ]
}

Example Responses

201 400 401 403 
{
  "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
Host https://api.nexmo.com
GET /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

external_id
string | Required

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

Responses

200 OK.
name
string

The account name

applications
array of strings

The array of associated application ids

external_id
string

The external identifier for this account

api_key
string

The external api key for this account

provider
string

The provider (will be messenger).

access_token
string

The provider access token

Example Responses

200 401 404 
{
  "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

Update a Messenger account

PATCH https://api.nexmo.com/beta/chatapp-accounts/messenger/:external_id
Host https://api.nexmo.com
PATCH /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

external_id
string | Required

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

Request body application/json

Request body can contain any of the following

name
string

The new account name

applications
array of strings
access_token
string

Responses

200 OK.
name
string

The account name

applications
array of strings

The array of associated application ids

external_id
string

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

api_key
string

The external api key for this account

provider
string

The provider (will be messenger).

access_token
string

The provider access token

Example Request

{
  "name": "newName",
  "applications": [
    "newApplicationId"
  ],
  "access_token": "updatedAccessToken"
}

Example Responses

200 400 401 403 404 
{
  "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 a Messenger account

DELETE https://api.nexmo.com/beta/chatapp-accounts/messenger/:external_id
Host https://api.nexmo.com
DELETE /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

external_id
string | Required

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

Example Responses

204 401 403 404 
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

Viber Service Message

Managing your Viber Service Message account

Available Operations:

Retrieve a Viber Service Message account

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

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

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

200 OK.
name
string

The account name

applications
array of strings

The array of associated application ids

external_id
string

The external identifier for this account

api_key
string

The external api key for this account

provider
string

The provider (will be viber_service_msg).

Example Responses

200 401 404 
{
  "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

Whatsapp

Managing your Whatsapp account

Available Operations:

Retrieve a Whatsapp account

GET https://api.nexmo.com/beta/chatapp-accounts/whatsapp/:external_id
Host https://api.nexmo.com
GET /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

external_id
string | Required

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

Responses

200 OK.
name
string

The account name

applications
array of strings

The array of associated application ids

external_id
string

The external identifier for this account

api_key
string

The external api key for this account

provider
string

The provider (will be whatsapp).

Example Responses

200 401 404 
{
  "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