Workflows API Developer Preview

The Workflows API enables the developer to specify a multiple message workflow. A workflow follows a template. The first one we are adding is the failover template. The failover template instructs the messaging API to first send a message to the specified channel. If that message fails immediately or if the condition_status is not reached within the given time period the next message is sent. The developer will also recieve status webhooks from the messages resource for each delivery and read event. This API is currently in Developer Preview and you will need to request access  to use it.

Download OpenAPI 3 Definition

Create a workflow

POST https://api.nexmo.com/beta /workflows

Authentication

  • Key
    Description
    Example
    Default
  • Authorization
    REQUIRED | string
    Your JSON web token.
    Read more about JWTs
    Bearer <JWT>
    None

Request body application/json

  • Key
    Description
    Example
    Default
  • template
    string

    The template that the workflow API will execute. For the initial version of the API the only available value will be failover


    Must be one of: failover
    failover
    None
  • workflow
    array
    None

    Any one of the following:

    Send With Failover Message
    • Key
      Description
      Example
      Default
    • to
      Required | object
      None
      • Key
        Description
        Example
        Default
      • type
        Required | string

        The type of message that you want to send.


        Must be one of: sms, viber_service_msgormessenger
        sms
        None
      • id
        string

        The ID of the message recipient.

        Messenger: This value should be the from.id value you received in the inbound messenger event.

        SMS: or Viber: This value is not required.

        0123456789012345
        None
      • number
        string

        SMS: or Viber: The phone number of the message recipient in the E.164  format.

        Messenger: This value is not required.

        447700900000
        None
    • from
      Required | object
      None
      • Key
        Description
        Example
        Default
      • type
        Required | string

        The type of message that you want to send.


        Must be one of: sms, viber_service_msgormessenger
        sms
        None
      • id
        string

        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 nexm.com/products/messages  .

        SMS: This value is not required.

        0123456789012345
        None
      • number
        string

        SMS: The phone number of the message recipient in the E.164  format.

        Messenger: or Viber: This value is not required.

        447700900000
        None
    • message
      Required | object
      None
      • Key
        Description
        Example
        Default
      • content
        Required | object
        None
        • Key
          Description
          Example
          Default
        • type
          string

          The type of message that you are sending.

          Messenger: supports all types.

          SMS or Viber only support text.


          Must be one of: text, image, audio, videoorfile
          text
          None
        • text
          string

          The text of the message.

          Messenger: Is limited to 640 characters

          SMS or Viber: Is 1000 characters

          Pretty majestical, aye?
          None
        • image
          object
          None
          • Key
            Description
            Example
            Default
          • url
            string

            The URL of the image attachment.

            https://example.com/image.jpg
            None
        • audio
          object
          None
          • Key
            Description
            Example
            Default
          • url
            string

            The URL of the audio attachment.

            https://example.com/audio.mp3
            None
        • video
          object
          None
          • Key
            Description
            Example
            Default
          • url
            string

            The URL of the video attachment.

            https://example.com/video.mp4
            None
        • file
          object
          None
          • Key
            Description
            Example
            Default
          • url
            string

            The URL of the file attachment.

            https://example.com/file.zip
            None
      • viber_service_msg
        object
        None
        • Key
          Description
          Example
          Default
        • ttl
          integer

          Only valid for Viber Service Messages. 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.


          Must be between 30 and 86400
          600
          None
    • failover
      object
      None
      • Key
        Description
        Example
        Default
      • expiry_time
        integer

        In seconds. Minimum value is 15 and maximum value is 86,400 seconds (1 day).


        Must be between 15 and 86400
        600
        None
      • condition_status
        string

        Set the status the message must reach in the expiry_time before failing over. Options are delivered or read.


        Must be one of: deliveredorread
        delivered
        None
    Send Message
    • Key
      Description
      Example
      Default
    • to
      Required | object
      None
      • Key
        Description
        Example
        Default
      • type
        Required | string

        The type of message that you want to send.


        Must be one of: sms, viber_service_msgormessenger
        sms
        None
      • id
        string

        The ID of the message recipient.

        Messenger: This value should be the from.id value you received in the inbound messenger event.

        SMS: or Viber: This value is not required.

        0123456789012345
        None
      • number
        string

        SMS: or Viber: The phone number of the message recipient in the E.164  format.

        Messenger: This value is not required.

        447700900000
        None
    • from
      Required | object
      None
      • Key
        Description
        Example
        Default
      • type
        Required | string

        The type of message that you want to send.


        Must be one of: sms, viber_service_msgormessenger
        sms
        None
      • id
        string

        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 nexm.com/products/messages  .

        SMS: This value is not required.

        0123456789012345
        None
      • number
        string

        SMS: The phone number of the message recipient in the E.164  format.

        Messenger: or Viber: This value is not required.

        447700900000
        None
    • message
      Required | object
      None
      • Key
        Description
        Example
        Default
      • content
        Required | object
        None
        • Key
          Description
          Example
          Default
        • type
          string

          The type of message that you are sending.

          Messenger: supports all types.

          SMS or Viber only support text.


          Must be one of: text, image, audio, videoorfile
          text
          None
        • text
          string

          The text of the message.

          Messenger: Is limited to 640 characters

          SMS or Viber: Is 1000 characters

          Pretty majestical, aye?
          None
        • image
          object
          None
          • Key
            Description
            Example
            Default
          • url
            string

            The URL of the image attachment.

            https://example.com/image.jpg
            None
        • audio
          object
          None
          • Key
            Description
            Example
            Default
          • url
            string

            The URL of the audio attachment.

            https://example.com/audio.mp3
            None
        • video
          object
          None
          • Key
            Description
            Example
            Default
          • url
            string

            The URL of the video attachment.

            https://example.com/video.mp4
            None
        • file
          object
          None
          • Key
            Description
            Example
            Default
          • url
            string

            The URL of the file attachment.

            https://example.com/file.zip
            None
      • viber_service_msg
        object
        None
        • Key
          Description
          Example
          Default
        • ttl
          integer

          Only valid for Viber Service Messages. 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.


          Must be between 30 and 86400
          600
          None

202 HTTP response

{
  "worflow_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

400 HTTP response

Callback  Message Status

staus of the message read or delivered etc.

POST https://example.com /webhooks/message-status

Request body application/json

  • Key
    Description
    Example
  • message_uuid
    string

    None

    aaaaaaaa-bbbb-cccc-dddd-0123456789ab
  • to
    Required | object
    • Key
      Description
      Example
    • type
      Required | string

      The type of message that you want to send.


      One of: sms, viber_service_msgormessenger
      sms
    • id
      string

      The ID of the message recipient.

      Messenger: This value should be the from.id value you received in the inbound messenger event.

      SMS: or Viber: This value is not required.

      0123456789012345
    • number
      string

      SMS: or Viber: The phone number of the message recipient in the E.164  format.

      Messenger: This value is not required.

      447700900000
  • from
    Required | object
    • Key
      Description
      Example
    • type
      Required | string

      The type of message that you want to send.


      One of: sms, viber_service_msgormessenger
      sms
    • id
      string

      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 nexm.com/products/messages  .

      SMS: This value is not required.

      0123456789012345
    • number
      string

      SMS: The phone number of the message recipient in the E.164  format.

      Messenger: or Viber: This value is not required.

      447700900000
  • timestamp
    string (ISO 8601)

    The datetime of when the event occurred.

    2020-01-01T14:00:00.000Z
  • status
    string

    The status of the message.


    One of: submitted, delivered, read, rejectedorundeliverable
    delivered
  • error
    object
    • Key
      Description
      Example
    • code
      integer

      The error code. See Errors for a table of descriptions.

      1300
    • reason
      string

      Text describing the error. See Errors for a more details.

      Not part of the provider network
  • usage
    object
    • Key
      Description
      Example
    • currency
      string

      The charge currency in ISO 4217 format.


      One of: EUR
      EUR
    • price
      string

      The charge amount as a stringified number.

      0.0333
  • _links
    object
    • Key
      Description
      Example
    • workflow
      object
      • Key
        Description
        Example
      • workflow_uuid
        string

        None

        aaaaaaaa-bbbb-cccc-dddd-0123456789ab
      • href
        string

        Please note GET is not currently supported

        /workflows/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

Request model

{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "to": {
    "type": "sms",
    "id": "0123456789012345",
    "number": "447700900000"
  },
  "from": {
    "type": "sms",
    "id": "0123456789012345",
    "number": "447700900000"
  },
  "timestamp": "2020-01-01T14:00:00.000Z",
  "status": "delivered",
  "error": {
    "code": 1300,
    "reason": "Not part of the provider network"
  },
  "usage": {
    "currency": "EUR",
    "price": "0.0333"
  },
  "_links": {
    "workflow": {
      "workflow_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
      "href": "/workflows/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
    }
  }
}

Callback  The Final Report

The final workflow callback is sent when The condition_status was met within the expiry_time. If we take the example API call above. If we received a delivered status at 300 seconds (within the expiry_time) the workflow would be marked as completed. We would not send an SMS. We would then send the final callback. The final message in the failover is delivered. If the message Errors on the last step we will send the final callback. Please note GET is not currently supported. You will notice we have an href to a resource in some of the callbacks. These will fail to load but we wanted to maintain the same structure so that we can seamlessly integrate GET later.

POST https://example.com /webhooks/final-report

Request body application/json

  • Key
    Description
    Example
  • workflow_uuid
    string

    None

    aaaaaaaa-bbbb-cccc-dddd-0123456789ab
  • template
    string

    None


    One of: failover
    failover
  • status
    string

    None


    One of: completedorerror
    completed
  • timestamp
    string (ISO 8601)

    The datetime of when the event occurred.

    2020-01-01T14:00:00.000Z
  • usage
    object

    This is the total cost of your Workflow request. Please note if a preceding message in the workflow request is delivered after the final message in the workflow is delivered it may not reflect the true total cost of the workflow.

    • Key
      Description
      Example
    • price
      string

      The charge amount as a stringified number.

      0.02
    • currency
      string

      The charge currency in ISO 4217 format.


      One of: EUR
      EUR
  • _links
    object
    • Key
      Description
      Example
    • messages
      array
      of object's
      • Key
        Description
        Example
      • message_uuid
        string

        None

        aaaaaaaa-bbbb-cccc-dddd-0123456789ab
      • href
        string

        Please note GET is not currently supported

        aaaaaaaa-bbbb-cccc-dddd-0123456789ab
      • channel
        string

        None


        One of: messenger, viber_sevice_msgorsms
        viber_service_msg
      • usage
        object
        • Key
          Description
          Example
        • currency
          string

          The charge currency in ISO 4217 format.


          One of: EUR
          EUR
        • price
          string

          The charge amount as a stringified number.

          0.0333
      • status
        string

        None


        One of: submitted, delivered, read, rejectedorundeliverable
        None

Request model

{
  "workflow_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "template": "failover",
  "status": "completed",
  "timestamp": "2020-01-01T14:00:00.000Z",
  "usage": {
    "price": "0.02",
    "currency": "EUR"
  },
  "_links": {
    "messages": [
      {
        "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
        "href": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
        "channel": "viber_service_msg",
        "usage": {
          "currency": "EUR",
          "price": "0.0333"
        },
        "status": "abc123"
      }
    ]
  }
}