{ "openapi": "3.0.1", "info": { "version": "0.1.6", "title": "External Accounts API", "x-metaTitle": "Vonage Account API Reference | Vonage API Documentation", "x-metaDescription": "Find quick answers to questions about the Vonage Account API in this reference guide. Learn more in Vonage's API documentation.", "description": "The External Accounts API is used to manage accounts for Viber Business 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:\n\n* Linking your Facebook Business Page to your account [with our Dashboard tool](${CUSTOMER_DASHBOARD_URL}/messages/social-channels/facebook-connect)\n* Requesting a Page Access Token using the steps in the [Facebook token reference](https://developers.facebook.com/docs/pages/access-tokens/)\n" }, "name": { "type": "string", "example": "optionalName", "description": "Custom account name" }, "applications": { "type": "array", "items": { "type": "string" }, "example": [ "78d335fa-323d-0114-9c3d-d6f0d48968cf" ], "minItems": 0, "maxItems": 1, "description": "Contains a list of application IDs which are linked to the account. 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": [ "78d335fa-323d-0114-9c3d-d6f0d48968cf" ] }, "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": [ "78d335fa-323d-0114-9c3d-d6f0d48968cf" ], "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", "rcs" ] }, "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", "rcs" ] }, "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, for RCS it will be the RCS Agent ID." } ], "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": "78d335fa-323d-0114-9c3d-d6f0d48968cf", "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", "rcs" ] }, "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", "description": "The account name" }, "applications": { "type": "array", "items": { "type": "string" }, "example": [ "78d335fa-323d-0114-9c3d-d6f0d48968cf" ], "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", "rcs" ], "example": "messenger", "description": "The provider (will be one of `messenger, viber_service_msg, whatsapp, rcs`)." }, "access_token": { "type": "string", "example": "accessToken", "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": [ "78d335fa-323d-0114-9c3d-d6f0d48968cf" ], "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": [ "78d335fa-323d-0114-9c3d-d6f0d48968cf" ], "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" } ] }