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:

                    * Linking your Facebook Business Page to your account [with our Dashboard tool](${CUSTOMER_DASHBOARD_URL}/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
                  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.
                    <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:
                    - 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
