openapi: "3.0.0"
info:
  version: 0.3.6
  title: Messages API
  description: 'The Messaging API is a new API that consolidates all messaging channels. It encapsulates a user (developer) from having to use multiple APIs to interact with our various channels such as SMS, MMS, Viber, Facebook Messenger, etc. The API normalises information across all channels to abstracted to, from and content. This API is currently in Beta.'
  contact:
    name: Nexmo DevRel
    email: devrel@nexmo.com
    url: 'https://developer.nexmo.com/'
  x-label: Beta
servers:
  - url: https://api.nexmo.com/v0.1/messages
paths:
  /:
    post:
      security:
        - bearerAuth: []
        - basicAuth: []
      summary: Send a Message
      operationId: NewMessage
      requestBody:
        description: Send a Message.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewMessage'
      responses:
        '202':
          description: Accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      callbacks:
        message-status:
          '{$request.body#/callback}':
            post:
              summary: Message Status
              operationId: message-status
              x-example-path: '/webhooks/message-status'
              description: 'Webhooks to inform about events happening to the message at communication level (has it been delivered, rejected by the provider...).'
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/MessageStatus'
              responses:
                  '200':
                    description: Your server returns this code if it accepts the callback.
        inbound-message:
          '{$request.body#/callback}':
            post:
              summary: Inbound Message
              operationId: inbound-message
              x-example-path: '/webhooks/inbound-message'
              description: An inbound message from a customer to you.
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/InboundMessage'
              responses:
                  '200':
                    description: Your server returns this code if it accepts the callback.


components:

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    basicAuth:
      type: http
      scheme: basic

  schemas:

    NewMessage:
      required:
        - to
        - from
        - message
      properties:
        to:
          $ref: '#/components/schemas/ToProperty'
        from:
          $ref: '#/components/schemas/FromProperty'
        message:
          $ref: '#/components/schemas/MessageProperty'
        client_ref:
          type: string
          description: Client reference of up to 40 characters. The reference will be present in every message status.
          example: 'my-personal-reference'

    Response:
      required:
        - message_uuid
      properties:
        message_uuid:
          type: string
          description: The UUID of the message.
          example: 'aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
    Error:
      description: 'The error format is standardized to the 4xx/5xx range with a code and a human readable explanation.'
      required:
        - type
        - title
        - detail
        - instance
      properties:
        type:
          type: string
          example: 'https://www.nexmo.com/messages/Errors#InvalidParams'
        title:
          type: string
          example: 'Invalid Parameters'
        detail:
          type: string
          example: 'Your request parameters did not validate.'
        instance:
          type: string
          example: f94b4e56604e07e5e5ad5a7228618f81

    MessageStatus:
      type: object
      required:
        - message_uuid
        - to
        - from
        - timestamp
        - status
      properties:
        message_uuid:
          type: string
          description: The UUID of the message.
          example: 'aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
        to:
          $ref: '#/components/schemas/ToProperty'
        from:
          $ref: '#/components/schemas/FromProperty'
        timestamp:
          $ref: '#/components/schemas/TimestampProperty'
        status:
          type: string
          example: delivered
          description: The status of the message. The `read` message status is available for `messenger`, `whatsapp` and `viber`.
          enum:
            - submitted
            - delivered
            - read
            - rejected
            - undeliverable
        error:
          type: object
          properties:
            code:
              type: integer
              example: 1300
              description: The error code. See [our errors list](https://developer.nexmo.com/api-errors/messages-olympus) for a list of possible errors
            reason:
              type: string
              example: 'Not part of the provider network'
              description: Text describing the error. See [our errors list](https://developer.nexmo.com/api-errors/messages-olympus) for a list of possible errors
        usage:
          type: object
          properties:
            currency:
              type: string
              example: EUR
              description: The charge currency in ISO 4217 format.
              enum:
                - EUR
            price:
              type: string
              example: '0.0333'
              description: The charge amount as a stringified number.
        client_ref:
          type: string
          description: The client's reference.
          example: 'my-personal-reference'

    InboundMessage:
      type: object
      required:
        - message_uuid
        - to
        - from
        - timestamp
      properties:
        message_uuid:
          type: string
          example: 'aaaaaaaa-bbbb-cccc-dddd-0123456789ab'
          description: The UUID of the message.
        to:
          type: object
          required:
            - type
          properties:
            type:
              type: string
              description: The type of message being received.
              example: messenger
              enum:
                - messenger
                - mms
                - whatsapp
                - viber_service_msg
            id:
              type: string
              example: '01234567'
              description: |
                **Messenger** or **Viber**: 
                The ID of the recipient.
            number:
              type: string
              minLength: 1
              maxLength: 50
              example: '447700900000'
              description: |
                **WhatsApp** or **MMS**: 
                The phone number of the message recipient in the [E.164](https://en.wikipedia.org/wiki/E.164) format.
        from:
          type: object
          required:
            - type
          properties:
            type:
              type: string
              description: The type of message being sent.
              example: messenger
              enum:
                - messenger
                - mms
                - whatsapp
                - viber_service_msg
            id:
              type: string
              description: The ID of the sender.
              example: '0123456789012345'
            number:
              type: string
              minLength: 1
              maxLength: 50
              example: '447700900000'
              description: |
                **WhatsApp** or **MMS** or **Viber**:
                The phone number of the message sender in the [E.164](https://en.wikipedia.org/wiki/E.164) format.
        timestamp:
          type: string
          format: ISO 8601
          description: The datetime of when the event occurred.
          example: '2020-01-01T14:00:00.000Z'
        message:
          type: object
          properties:
            content:
              type: object
              properties:
                type:
                  type: string
                  description: |
                    The type of message being received. 
                    **whatsapp** and **messenger** supports `text`, `image`, `audio`, `video`, `file` and `location`. WhatsApp maximum inbound size is 64mb.
                    **mms** supports `image`.
                    **viber** supports `text`.
                  example: 'text'
                  enum:
                    - text
                    - image
                    - audio
                    - video
                    - file
                    - location
                text:
                  type: string
                  description: The body of the message.
                  example: 'Hello World!'
                image:
                  $ref: '#/components/schemas/ImageProperty'
                audio:
                  $ref: '#/components/schemas/AudioProperty'
                video:
                  $ref: '#/components/schemas/VideoPropertyInbound'
                file:
                  $ref: '#/components/schemas/FileProperty'
                location:
                  $ref: '#/components/schemas/LocationProperty'

    ToProperty:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: The type of message that you want to send.
          example: 'sms'
          enum:
            - sms
            - viber_service_msg
            - messenger
            - whatsapp
            - mms
        id:
          description: |
            **Messenger**: The ID of the message recipient. This value should be the `from.id` value you received in the inbound messenger event.
          type: string
          minLength: 1
          maxLength: 50
          example: '0123456789012345'
        number:
          type: string
          minLength: 1
          maxLength: 50
          example: '447700900000'
          description: |
           **SMS**, **Viber**, **WhatsApp** or **MMS**: 
           The phone number of the message recipient in the [E.164](https://en.wikipedia.org/wiki/E.164) format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.
    FromProperty:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: The type of message that you want to send.
          example: sms
          enum:
            - sms
            - viber_service_msg
            - messenger
            - whatsapp
            - mms
        id:
          description: |
            Your ID for the platform that you are sending from.

            **Messenger**: This value should be the `to.id` value you received in the inbound messenger event.

            **Viber**: This is your Service Message ID given to you by Nexmo Account Manager. To find out more please visit [nexmo.com/products/messages](https://www.nexmo.com/products/messages).

          type: string
          minLength: 1
          maxLength: 50
          example: '0123456789012345'
        number:
          type: string
          minLength: 1
          maxLength: 50
          example: '447700900000'
          description: |
            **SMS**: The phone number of the message recipient in the [E.164](https://en.wikipedia.org/wiki/E.164) format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.

            **WhatsApp**: This is your WhatsApp Business Number  given to you by Nexmo Account Manager. To find out more please visit [nexmo.com/products/messages](https://www.nexmo.com/products/messages).

            **MMS**: US shortcode
    MessageProperty:
      type: object
      required:
        - content
      properties:
        content:
          type: object
          properties:
            type:
              description: |
                The type of message that you are sending.

                **Messenger**: supports `text`, `image`, `audio`, `video` and `file`.

                **Viber Service Messages**: supports `image`, `text` and `custom`.

                **WhatsApp**: supports `template`, `text`, `image`, `audio`, `file`, `video` and `custom`. Maximum outbound media size is 64mb.

                **SMS**: supports `text`.

                **MMS**: supports `image`.
              type: string
              enum:
                - text
                - image
                - audio
                - video
                - file
                - template
                - custom
              example: 'text'
            text:
              description: |
                The text of the message.

                **Messenger**: is limited to 640 characters, including unicode.

                **SMS**: is limited to 1000 characters. The Messages API automatically detects unicode characters when sending SMS and sends the message as a unicode SMS. For more information on how concatenation and encoding please visit: [developer.nexmo.com/messaging/sms/guides/concatenation-and-encoding](https://developer.nexmo.com/messaging/sms/guides/concatenation-and-encoding).

                **Viber**: is limited to 1000 characters, including unicode. 

                **WhatsApp**: is limited to 4096 characters, including unicode.
              type: string
              minLength: 1
              maxLength: 4096
              example: 'Nexmo Verification code: 64873. Valid for 10 minutes.'
            image:
              $ref: '#/components/schemas/ImageProperty'
            audio:
              $ref: '#/components/schemas/AudioProperty'
            video:
              $ref: '#/components/schemas/VideoProperty'
            file:
              $ref: '#/components/schemas/FileProperty'
            template:
              $ref: '#/components/schemas/TemplateProperty'
            # @TODO: Clarify requirements
            # custom:
            #   type: object
            #   description: This is a highly experimental feature. To enable the user to send any type of Messenger message we have included a custom object. To use this feature include the original Messenger API payload from the message object onwards.
            #   properties:
            #     custom:
            #       type: object
        viber_service_msg:
          type: object
          properties:
            category:
              description: 'The use of different category tags enables the business to send messages for different use cases. For Viber Service Messages the first message sent from a business to a user must be personal, informative & a targeted message - not promotional. By default Nexmo sends the `transaction` category to Viber Service Messages.'
              type: string
              example: 'transaction'
              enum:
                - transaction
                - promotion
            ttl:
              description: 'Set the time-to-live of message to be delivered in seconds. i.e. if the message is not delivered in 600 seconds then delete the message.'
              type: integer
              example: 600
              minimum: 30
              maximum: 259200
            type:
              description: 'Viber-specific type definition. To use "template", please contact Nexmo Account Manager to setup your templates. To find out more please visit [nexmo.com/products/messages](https://www.nexmo.com/products/messages).'
              type: string
              example: 'template'
        messenger:
          type: object
          properties:
            category:
              description: 'The use of different category tags enables the business to send messages for different use cases. For Facebook Messenger they need to comply with their [Messaging Types policy]( https://developers.facebook.com/docs/messenger-platform/send-messages#messaging_types). Nexmo maps our `category` to their `messaging_type`. If `message_tag` is used, then an additional `tag` for that type is mandatory. By default Nexmo sends the `response` category to Facebook Messenger.'
              type: string
              example: 'message_tag'
              enum:
                - response
                - update
                - message_tag
            tag:
              description: ‘A full list of the possible tags is available on [developers.facebook.com](https://developers.facebook.com/docs/messenger-platform/send-messages/message-tags)'
              type: string
              example: 'ticket_update'
        whatsapp:
          type: object
          properties:
            policy:
              description: 'Please note that WhatsApp will deprecate `fallback` policy in January 2020. There are two policies that you can specify when sending a Message Template: `deterministic` and `fallback`. `deterministic` — Deliver the Message Template in exactly the language and locale asked for. `fallback` — Deliver the Message Template in the language that matches users language/locale setting on device. If one can not be found, deliver using the specified fallback language.'
              type: string
              example: 'deterministic'
              enum:
                - fallback
                - deterministic
            locale:
              description: 'We are using the industry standard, BCP 47, for locales. So in your API call to the /messages API you will need to put “en-GB” and this will refer to the “en_GB” template for WhatsApp. A full list of the possible locales is available on [developers.facebook.com](https://developers.facebook.com/docs/whatsapp/message-templates/creation#translations).'
              type: string
              example: 'en-GB'


    TimestampProperty:
      type: string
      format: ISO 8601
      description: The datetime of when the event occurred.
      example: '2020-01-01T14:00:00.000Z'

    ImageProperty:
      type: object
      properties:
        url:
          type: string
          description: |
            The URL of the image attachment. 

            **messenger** and **mms** supports .jpg, .jpeg, .png and .gif.

            **whatsapp** and **viber_service_msg** supports .jpg .jpeg, and .png.
          minLength: 10
          maxLength: 2000
          example: 'https://example.com/image.jpg'
        caption:
          type: string
          description: 'Additional text to accompany the image. Supported by WhatsApp and MMS.'
          minLength: 1
          maxLength: 3000
          example: 'Additional text to accompany the image.'
    AudioProperty:
      type: object
      properties:
        url:
          type: string
          description: |
            The URL of the audio attachment.

            **messenger** supports .mp3.

            **whatsapp** supports .aac, .m4a, .amr, .mp3 and .opus.
          minLength: 10
          maxLength: 2000
          example: 'https://example.com/audio.mp3'
    VideoProperty:
      type: object
      properties:
        url:
          type: string
          description: |
            The URL of the video attachment.
            
            **messenger** supports .mp4
            
            **whatsapp** supports .mp4 and .3gpp. Note, only H.264 video codec and AAC audio codec is supported.
          minLength: 10
          maxLength: 2000
          example: 'https://example.com/video.mp4'
    VideoPropertyInbound:
      type: object
      properties:
        url:
          type: string
          description: |
            The URL of the video attachment.

            **messenger** and **whatsapp** supports .mp4.
          minLength: 10
          maxLength: 2000
          example: 'https://example.com/video.mp4'
        caption:
          type: string
          description: 'Additional text to accompany the image. Only supported by WhatsApp. Only present if specified.'
          minLength: 1
          maxLength: 3000
          example: 'Additional text to accompany the image.'
    FileProperty:
      type: object
      properties:
        url:
          type: string
          description: |
            The URL of the file attachment.

            **messenger** supports a wide range of attachments including .zip, .csv and .pdf.

            **whatsapp** supports .pdf, .doc(x), .ppt(x) and .xls(x).'
          minLength: 10
          maxLength: 2000
          example: 'https://example.com/file.zip'
        caption:
          type: string
          description: 'Additional text to accompany the image. Only supported by WhatsApp. Optional. Only present if specified.'
          minLength: 1
          maxLength: 3000
          example: 'Additional text to accompany the image.'
    TemplateProperty:
      type: object
      properties:
        name:
          type: string
          description: 'The name of the template. For WhatsApp use your Whatsapp namespace (available via Facebook Business Manager), followed by a colon `:` and the name of the template to use.'
          example: 'WhatsApp_namespace:template_name'
        parameters:
          type: array
          items:
            type: object
            properties:
              default:
                type: string
                description: 'The parameters are an array. The first value being {{1}} in the template.'
                example: '1234'

    LocationProperty:
      type: object
      properties:
        lat:
          type: string
          description: The latitude of the location attachment.
          example: '51.5228349'
        long:
          type: string
          description: The longitude of the location attachment.
          example: '-0.0854414'
        url:
          type: string
          description: Depending on the provider, this can either be the location on a map or the website of the business at this location.
        address:
          type: string
          description: The address of the location attachment.
          example: '15 Bonhill St London EC2A 4DN'
        name:
          type: string
          description: The name of the location attachment.
          example: 'Nexmo London'

x-errors:
  "1000":
    description: Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry

  "1010":
    description: Missing params - Your request is incomplete and missing some mandatory parameters.

  "1020":
    description: Invalid params  -  The value of one or more parameters is invalid.

  "1021":
    description: Invalid tag  -  The tag value is invalid.

  "1022":
    description: Invalid template  -  Invalid template or template parameters

  "1030":
    description: Internal error  -  There was an error processing your request in the Platform.

  "1040":
    description: Invalid message  -  The Platform was unable to process your request. For example, due to an unrecognised prefix for the phone number.

  "1050":
    description: Number barred  -  The number you are trying to submit to is blacklisted and may not receive messages.

  "1060":
    description: Partner account barred  -  The `api_key` you supplied is for an account that has been barred from submitting messages.

  "1070":
    description: Partner quota exceeded  -  Your pre-paid account does not have sufficient credit to process this message.

  "1080":
    description: Account not enabled for REST  -  This account is not provisioned for REST submission, you should use SMPP on the SMS API.

  "1090":
    description: Message too long  -  The length of `udh` and `body` was greater than 140 octets for a binary type SMS request.

  "1100":
    description: Communication Failed  -  Message was not submitted because there was a communication failure.

  "1120":
    description: Illegal Sender Address - rejected  -  Due to local regulations, the `SenderID` you set in from in the request was not accepted. Please check the Global messaging section.

  "1130":
    description: Invalid TTL  -  The value of `ttl` in your request was invalid.

  "1140":
    description: Facility not allowed  -  Your request makes use of a facility that is not enabled on your account.

  "1150":
    description: Invalid Message class  -  The value of `message-`class in your request was out of range. See https://en.wikipedia.org/wiki/Data_Coding_Scheme.

  "1160":
    description: Non White-listed Destination  -  The phone number you set in to is not in your pre-approved destination list. To send messages to this phone number, add it using Dashboard.

  "1170":
    description: Invalid or Missing Msisdn Param  -  The phone number you supplied in the to parameter of your request was either missing or invalid.

  "1180":
    description: Absent Subscriber Temporary  -  This message was not delivered because to was temporarily unavailable. For example, the handset used for to was out of coverage or switched off. This is a temporary failure, retry later for a positive result.

  "1190":
    description: Absent Subscriber Permanent  -  `to` is no longer active, You should remove this phone number from your database.

  "1200":
    description: Portability Error  -  There is an issue after the user has changed carrier for to. If the user wants to receive messages from you, they need to contact their carrier directly.

  "1210":
    description: Anti-Spam Rejection  -  Carriers often apply restrictions that block messages following different criteria. For example on SenderID or message content.

  "1220":
    description: Handset Busy  -  The handset associated with to was not available when this message was sent. If status is rejected, this is a temporary failure; retry later for a positive result. If status is submitted, this message has is in the retry scheme and will be resent until it expires in 24-48 hours.

  "1230":
    description: Network Error  -  A network failure while sending your message. This is a temporary failure, retry later for a positive result.

  "1240":
    description: Illegal Number  -  You tried to send a message to a blacklisted phone number. That is, the user has already sent a STOP opt-out message and no longer wishes to receive messages from you.

  "1241":
    description: Too many send requests  -  Too many send requests to phone numbers.

  "1250":
    description: Unroutable  -  The chosen route to send your message is not available. This is because the phone number is either currently on an unsupported network or on a pre-paid or reseller account that could not receive a message sent by from. To resolve this issue either email us at support@nexmo.com or create a helpdesk ticket at https://help.nexmo.com.

  "1260":
    description: Destination unreachable  -  The message could not be delivered to the phone number. If using Viber Service Messages your account might not be enabled for this country.

  "1270":
    description: Subscriber Age Restriction  -  The carrier blocked this message because the content is not suitable for to based on age restrictions.

  "1280":
    description: Number Blocked by Carrier  -  The carrier blocked this message. This could be due to several reasons. For example, to's plan does not include SMS or the account is suspended.

  "1290":
    description: Pre-Paid - Insufficient funds  -  to’s pre-paid account does not have enough credit to receive the message.

  "1300":
    description: Not part of the provider network  -  The number or ID is not a user in the provider network.

  "1310":
    description: Not suitable device  -  The user's device can't receive the message.

  "1320":
    description: Message already sent  -  The message was already sent.

  "1330":
    description: Unknown  -  An unknown error was received from the carrier who tried to send this this message. Depending on the carrier, that to is unknown. When you see this error, and status is rejected, always check if to in your request was valid.
  
  "1331":
    description: Provider error  -  The provider is not responding or unable to process the request. Please try sending your message in a few minutes time.

  "1340":
    description: Outside of the allowed window  -  This message is sent outside of allowed response window.

  "1350":
    description: Phone matching fee not paid  -  Requires phone matching access fee to be paid by the Facebook Page.

  "1360":
    description: TTL was activated  -  TTL was activated, no callbacks and no charge will be issued.

  "1370":
    description: Expired access Token - Please reauthenticate your Facebook Page with Nexmo.
  
  "1380":
    description: Invalid resource - Please check that the URL your provided to your resrouce is accesible and valid.
  
  "1381":
    description: Resource size is too large - Please try sending a smaller media file.
    
  "1382":
    description: Resource type is invalid - Please check that the file you are trying to send is valid.
