Skip to content
Permalink
main
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time
openapi: "3.0.0"
info:
version: 0.1.5
title: External Accounts API
description: "The External Accounts API is used to manage accounts for Viber Service Messages, Facebook Messenger and Whatsapp for use in the [Messages](https://developer.nexmo.com/messages/overview) and [Dispatch](https://developer.nexmo.com/dispatch/overview) APIs."
x-label: Developer Preview
contact:
name: Vonage DevRel
email: devrel@vonage.com
url: "https://developer.nexmo.com/"
servers:
- url: https://api.nexmo.com/beta/chatapp-accounts
paths:
/messenger:
post:
security:
- bearerAuth: []
- basicAuth: []
summary: Create a Messenger account
operationId: CreateMessengerAccount
tags:
- Facebook Messenger
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- external_id
- access_token
properties:
external_id:
type: string
example: "12345678"
description: 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:
type: string
example: "myAccessToken"
description: |
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](https://dashboard.nexmo.com/messages/social-channels/facebook-connect)
* Requesting a Page Access Token using the steps in the [Facebook token reference](https://developers.facebook.com/docs/pages/access-tokens/)
name:
type: string
example: "optionalName" # optional
description: Custom account name
applications:
type: array
items:
type: string
example: ["optionalApplicationId"]
minItems: 0
maxItems: 1
description:
Contains a list of application IDs which are linked to the account.
<ul>
<li>There is just one application allowed per an account.</li>
<li>The application type must be type "messages".</li>
</ul>
For more information see [Application API spec](https://developer.nexmo.com/api/application.v2)
responses:
"201":
description: Created.
content:
application/json:
schema:
$ref: "#/components/schemas/MessengerAccountResponse"
"400":
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
type:
type: string
example: "https://www.nexmo.com/messages/Errors#InvalidParams"
title:
type: string
example: "Your request parameters didn't validate."
detail:
type: string
example: "Found errors validating 1 of your submitted parameters."
instance:
type: string
example: null
invalid_params:
type: "array"
items:
type: "object"
properties:
name:
type: string
example: "external_id"
reason:
type: string
example: "Missing `external_id` field"
"401":
description: Unauthorized.
content:
application/json:
schema:
$ref: "#/components/schemas/401Response"
"403":
description: Forbidden.
content:
application/json:
schema:
$ref: "#/components/schemas/403Response"
/messenger/{external_id}:
get:
security:
- bearerAuth: []
- basicAuth: []
summary: Retrieve a Messenger account
operationId: GetMessengerAccount
tags:
- Facebook Messenger
parameters:
- in: path
name: external_id
schema:
type: string
required: true
description: External id of the account you want to retrieve. In this case it is the Facebook Page ID.
responses:
"200":
description: OK.
content:
application/json:
schema:
$ref: "#/components/schemas/MessengerAccountResponse"
"401":
description: Unauthorized.
content:
application/json:
schema:
$ref: "#/components/schemas/401Response"
"404":
description: Not Found.
patch:
security:
- bearerAuth: []
- basicAuth: []
summary: Update a Messenger account
operationId: UpdateMessengerAccount
tags:
- Facebook Messenger
parameters:
- in: path
name: external_id
schema:
type: string
required: true
description: External id of the account you want to update. In this case it is the Facebook Page ID.
requestBody:
description: Request body can contain any of the following
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: "newName"
description: The new account name
applications:
type: "array"
items:
type: string
example: ["newApplicationId"]
access_token:
type: string
example: "updatedAccessToken"
responses:
"200":
description: OK.
content:
application/json:
schema:
type: object
required:
- external_id
- api_key
- provider
- access_token
properties:
name:
type: string
example: "newName"
description: The account name
applications:
type: "array"
items:
type: string
example: ["newApplicationId"]
description: The array of associated application ids
external_id:
type: string
example: "12345678"
description: The external identifier for this account. In this case it is the Facebook Page ID.
api_key:
type: string
example: "abcd1234"
description: The external api key for this account
provider:
type: string
example: "messenger"
description: The provider (will be `messenger`).
access_token:
type: string
example: "updatedAccessToken"
description: The provider access token
"400":
description: Bad Request.
content:
application/json:
schema:
type: object
properties:
type:
type: string
example: "https://www.nexmo.com/messages/Errors#InvalidParams"
title:
type: string
example: "Your request parameters didn't validate."
detail:
type: string
example: "Found errors validating 1 of your submitted parameters."
instance:
type: string
example: null
invalid_params:
type: "array"
items:
type: "object"
properties:
name:
type: string
example: "external_id"
reason:
type: string
example: "'external_id' parameter cannot be changed"
"401":
description: Unauthorized.
content:
application/json:
schema:
$ref: "#/components/schemas/401Response"
"403":
description: Forbidden.
content:
application/json:
schema:
$ref: "#/components/schemas/403Response"
"404":
description: Not Found.
delete:
security:
- bearerAuth: []
- basicAuth: []
summary: Delete a Messenger account
operationId: DeleteMessengerAccount
tags:
- Facebook Messenger
parameters:
- in: path
name: external_id
schema:
type: string
required: true
description: External id of the account you want to delete. In this case it is the Facebook Page ID.
responses:
"204":
description: No Content.
"401":
description: Unauthorized.
content:
application/json:
schema:
$ref: "#/components/schemas/401Response"
"403":
description: Forbidden.
content:
application/json:
schema:
$ref: "#/components/schemas/403Response"
"404":
description: Not Found.
/viber_service_msg/{external_id}:
get:
security:
- bearerAuth: []
- basicAuth: []
summary: Retrieve a Viber Service Message account
operationId: GetVSMAccount
tags:
- Viber Service Message
parameters:
- in: path
name: external_id
schema:
type: string
required: true
description: External id of the account you want to retrieve. In this case it will be your Viber Service Message ID.
responses:
"200":
description: OK.
content:
application/json:
schema:
$ref: "#/components/schemas/VSMAccountResponse"
"401":
description: Unauthorized.
content:
application/json:
schema:
$ref: "#/components/schemas/401Response"
"404":
description: Not Found.
/whatsapp/{external_id}:
get:
security:
- bearerAuth: []
- basicAuth: []
summary: Retrieve a Whatsapp account
operationId: GetWAAccount
tags:
- WhatsApp
parameters:
- in: path
name: external_id
schema:
type: string
required: true
description: External id of the account you want to retrieve. In this case it will be the WhatsApp number.
responses:
"200":
description: OK.
content:
application/json:
schema:
$ref: "#/components/schemas/WAAccountResponse"
"401":
description: Unauthorized.
content:
application/json:
schema:
$ref: "#/components/schemas/401Response"
"404":
description: Not Found.
/:
get:
security:
- bearerAuth: []
- basicAuth: []
summary: Retrieve all accounts you own
operationId: GetAllAccounts
tags:
- Account
parameters:
- in: query
name: provider
schema:
type: string
enum:
- messenger
- viber_service_msg
- whatsapp
required: false
description: Filter by provider
- in: query
name: page_number
schema:
type: integer
example: 1
default: 1
required: false
description: Page number of the results
- in: query
name: page_size
schema:
type: integer
example: 1
default: 20
required: false
description: Page size of the results
responses:
"200":
description: OK.
content:
application/json:
schema:
type: object
properties:
page_number:
type: integer
example: 1
page_size:
type: integer
example: 10
_embedded:
type: "array"
items:
$ref: "#/components/schemas/GetAllAccountResponse"
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
example: "https://api.nexmo.com/beta/chatapp-accounts?page_number=1&page_size=10"
next:
type: object
properties:
href:
type: string
example: "https://api.nexmo.com/beta/chatapp-accounts?page_number=3&page_size=10"
prev:
type: object
properties:
href:
type: string
example: "https://api.nexmo.com/beta/chatapp-accounts?page_number=1&page_size=10"
first:
type: object
properties:
href:
type: string
example: "https://api.nexmo.com/beta/chatapp-accounts?page_number=1&page_size=10"
last:
type: object
properties:
href:
type: string
example: "https://api.nexmo.com/beta/chatapp-accounts?page_number=4&page_size=10"
"401":
description: Unauthorized.
content:
application/json:
schema:
$ref: "#/components/schemas/401Response"
/{provider}/{external_id}/applications:
post:
security:
- bearerAuth: []
- basicAuth: []
summary: Link application to an account
operationId: LinkApplication
tags:
- Application
parameters:
- in: path
name: provider
schema:
type: string
enum:
- messenger
- viber_service_msg
- whatsapp
required: true
description: Provider of the account you want to assign an application to
- in: path
name: external_id
schema:
type: string
required: true
description: 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.
requestBody:
description: Request body can contain any of the following. Please note, the only one application can be linked to the account.
required: true
content:
application/json:
schema:
type: object
required:
- application
properties:
application:
type: string
example: "applicationId"
description: There is just one application allowed per an account. The application type must be type "messages". For more information please see [Application API Spec](https://developer.nexmo.com/api/application.v2)
responses:
"200":
description: OK.
content:
application/json:
schema:
$ref: "#/components/schemas/AccountResponse"
"401":
description: Unauthorized.
content:
application/json:
schema:
$ref: "#/components/schemas/401Response"
"403":
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
type:
type: string
example: "https://www.nexmo.com/messages/Errors#Forbidden"
title:
type: string
example: "Forbidden"
detail:
type: string
example: "Cannot link application"
description: The application does not exist or the application type is not "messages"
"409":
description: Conflict.
content:
application/json:
schema:
type: object
properties:
type:
type: string
example: "https://www.nexmo.com/messages/Errors#Conflict"
title:
type: string
example: "Application conflict"
detail:
type: string
example: "Unable to link application"
description: The account reached limit of maximum number of linked applications. (The only one application is allowed per an account)
/{provider}/{external_id}/applications/{application_id}:
delete:
security:
- bearerAuth: []
- basicAuth: []
summary: Unlink application from an account
operationId: UnliWithoutApplicationnkApplication
tags:
- Application
parameters:
- in: path
name: provider
schema:
type: string
enum:
- messenger
- viber_service_msg
- whatsapp
required: true
description: Provider of the account you want to unlink an application from
- in: path
name: external_id
schema:
type: string
required: true
description: External id of the account you want to unlink an application from
- in: path
name: application_id
schema:
type: string
required: true
description: Id of the application you want to unlink
responses:
"204":
description: No Content.
"401":
description: Unauthorized.
content:
application/json:
schema:
$ref: "#/components/schemas/401Response"
"403":
description: Forbidden.
content:
application/json:
schema:
type: object
properties:
type:
type: string
example: "https://www.nexmo.com/messages/Errors#Forbidden"
title:
type: string
example: "Forbidden"
detail:
type: string
example: "Cannot unlink application"
"409":
description: Conflict.
content:
application/json:
schema:
type: object
properties:
type:
type: string
example: "https://www.nexmo.com/messages/Errors#Conflict"
title:
type: string
example: "Application conflict"
detail:
type: string
example: "Unable to unlink application"
description: The application is not linked or doesn't exist.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
basicAuth:
type: http
scheme: basic
schemas:
AccountResponse:
type: object
required:
- external_id
- api_key
- provider
properties:
name:
type: string
example: "name" #optional
description: The account name
applications:
type: "array"
items:
type: string
example: ["applicationId"]
description: The array of associated application ids
external_id:
type: string
example: "12345678"
description: The external identifier for this account
api_key:
type: string
example: "abcd1234"
description: The external api key for this account
provider:
type: string
enum:
- messenger
- viber_service_msg
- whatsapp
example: "messenger"
description: The provider (will be one of `messenger, viber_service_msg, whatsapp`).
access_token:
type: string
example: "accessToken" #optional
description: The provider access token (only for `messenger`)
MessengerAccountResponse:
type: object
required:
- external_id
- api_key
- provider
- access_token
properties:
name:
type: string
example: "optionalName"
description: The account name
applications:
type: "array"
items:
type: string
example: ["optionalApplicationId"]
description: The array of associated application ids
external_id:
type: string
example: "12345678"
description: The external identifier for this account
api_key:
type: string
example: "abcd1234"
description: The external api key for this account
provider:
type: string
example: "messenger"
description: The provider (will be `messenger`).
access_token:
type: string
example: "myAccessToken"
description: The provider access token
VSMAccountResponse:
type: object
required:
- external_id
- api_key
- provider
properties:
name:
type: string
example: "optionalName"
description: The account name
applications:
type: "array"
items:
type: string
example: ["optionalApplicationId"]
description: The array of associated application ids
external_id:
type: string
example: "12345678"
description: The external identifier for this account
api_key:
type: string
example: "abcd1234"
description: The external api key for this account
provider:
type: string
example: "viber_service_msg"
description: The provider (will be `viber_service_msg`).
WAAccountResponse:
type: object
required:
- external_id
- api_key
- provider
properties:
name:
type: string
example: "optionalName"
description: The account name
applications:
type: "array"
items:
type: string
example: ["optionalApplicationId"]
description: The array of associated application ids
external_id:
type: string
example: "12345678"
description: The external identifier for this account
api_key:
type: string
example: "abcd1234"
description: The external api key for this account
provider:
type: string
example: whatsapp
description: The provider (will be `whatsapp`).
GetAllAccountResponse:
allOf:
- $ref: "#/components/schemas/MessengerAccountResponse"
- $ref: "#/components/schemas/VSMAccountResponse"
- $ref: "#/components/schemas/WAAccountResponse"
401Response:
type: object
properties:
title:
type: string
example: "Unauthorised"
detail:
type: string
example: "Request header 'Authorization' missing / Invalid Token"
403Response:
type: object
properties:
title:
type: string
example: "Wrong authentication - You are not authorised to access this resource"
tags:
- name: "Application"
description: Inbound messages to an external account which is linked to an application will be delivered to the application's inbound URL.
- name: "Account"
description: An external-account used as the `from` field in the Messages API and Dispatch API
- name: "Facebook Messenger"
description: "Managing your [Facebook Messenger](https://developer.nexmo.com/messages/concepts/facebook) account"
- name: "Viber Service Message"
description: "Managing your [Viber Service Message](https://developer.nexmo.com/messages/concepts/viber) account"
- name: "Whatsapp"
description: "Managing your [Whatsapp](https://developer.nexmo.com/messages/concepts/whatsapp) account"