OLD - Getting started with Automation API

🚧

[BETA]

This product is currently in early access. Please reach out to your account manager to get more information.

Overview

The Automation API allows you to create and manage complex business workflows. A workflow is a sequence of triggers, conditions and actions which we will be running for you, it can be seen as a business logic.

We will be using the following terms in this document:

• Workflow definition, the blueprint of a business flow.
• Workflow instance, the runtime object that executes the business logic defined in the corresponding workflow definition.
• Trigger, an external event that starts a workflow without manual intervention.
• Step, a basic building block of a workflow definition which represents an action to be taken.
• Branch, a step that allows you to define alternate paths for the workflow based on conditions.
• Workflow context, data captured in a workflow instance which persists between steps.

‎

Use Cases

The Automation API allows you to tackle many business processes, here are some examples of the most common use cases:

• Auto Reply: for each incoming message (SMS or ChatApps) I want to send an automatic reply to the user. It can be to acknowledge reception or to share a link for support enquiries.

• Out of Office: outside of business hours, I want to send an automatic reply to the users, to let them know when I will get back to them.

• Fallback: for each undelivered outbound message, I want to call another API to make sure my message got delivered through another channel.

• Split messages: for all messages coming from a +1 (US) number, I want to send them to a CRM using a custom API call. For all other messages, I want to send them to a different CRM.

• Custom integration: I want some of the incoming messages to be pushed to my ordering system, for this I will use the Automation service to make a custom API call to my system.

• Content based rule: I'm running a campaign where users need to send a specific message to my number. I can filter only the message with this content, to confirm customers they are enrolled and push the registered user numbers to my system, using an API call.

• Mix and match: mix any of the examples above. For example, for messages outside of business hours coming from a +44 (UK) number, I want to send an auto reply. For all messages coming from +65 (Singapore) number, I want to do a custom API call and for all the other messages do nothing.

These are just some example, as you can design the workflow definitions, you can create many more flows to support other use cases. Feel free to contact us for support.

‎

Authentication

Automation API uses Bearer authentication scheme. All requests to automation server must contain the HTTP authorization header with the value Bearer {apiKey} where {apiKey} for the account can be obtained from 8x8 Connect https://connect.8x8.com/. The account must be registered in the automation service before it can be used (please reach out to your account manager for more information).

How to use the API

Here is how you would likely interact with the Automation API:

WORKFLOW CREATION

1. Create a new workflow definition, you are submitting your blueprint
   -> https://developer.8x8.com/connect/reference#create-definition

WORKFLOW DEFINITION MANAGEMENT

2. Get your workflow definitions, to make sure your definition is there
   -> https://developer.8x8.com/connect/reference#get-all-definitions

3. Retrieve your workflow, based on the workflowId, to verify it
   -> https://developer.8x8.com/connect/reference#get-specific-definition

4. If you want to modify your definition, you can use this
   -> https://developer.8x8.com/connect/reference#update-existing-definition

5. If you want to delete your definition, you can use this
   -> https://developer.8x8.com/connect/reference#delete-definitions

WORKFLOW INSTANCE MANAGEMENT
6) To test your workflow, you can trigger it manually
-> https://developer.8x8.com/connect/reference#start-workflow-instance

7. To retrieve the workflow instance of a specific workflow definition
   -> https://developer.8x8.com/connect/reference#get-workflow-instances

8. To suspend, resume or terminate a workflow instance
   -> https://developer.8x8.com/connect/reference#patch-workflow-instance

9. To get errors of a workflow instance
   -> https://developer.8x8.com/connect/reference#get-instance-errors

As you can see, only the step #1 is mandatory.
If you know that your workflow is valid, and that you can test it without the API (by actually sending an incoming message for example), you only need to perform the first step (create a workflow definition).

The other items are here to help you manage your workflow definition, test them manually and debug them.

‎

Workflow definition example

Here is a simple example of a workflow definition.

This definition contains the following attributes:

• the trigger is any Inbound Chat Apps message on the subaccount Test_12345_ChatApps
• there are no conditions, all instances will result in sending a Chat Apps message
• the instance will send an auto reply message to any incoming Chat Apps message

{
        "subAccountId": "Test_12345_ChatApps",
        "trigger": "inbound_chat_apps",
        "definition": {
            "name": "Auto Reply ChatApps",
            "steps": [
                {
                    "id": "send_CA",
                    "stepType": "ChatAppsMessage",
                    "inputs": {
                        "subAccountId": "Test_12345_ChatApps",
                        "user": {
                            "msisdn": "{{data.payload.user.msisdn}}"
                        },
                        "type": "text",
                        "content": {
                            "text": "Hello, thank you for your message, we will get back to you as soon as possible."
                        }
                    }
                }
            ]
        }
    }

‎

Triggers

Here are the different triggers we support, at the moment:

inbound_sms : meaning when you receive a new incoming SMS on the specified subaccount.

outbound_sms : meaning when you receive a new Delivery Receipt for SMS on the specified subaccount.

inbound_chat_apps : meaning when you receive a new incoming ChatApps message on the specified subaccount.

One workflow definition can only have one trigger, defining a trigger is mandatory.
You can create similar workflows with different triggers, if needed.

‎

Steps

Workflow definitions are collections of workflow steps. Every step must have an id and a step type. The id of the step must be unique within the workflow definition. Steps may have properties that can be set when you are creating a workflow definition (e.g. set a HTTP header for a HTTP request) or at runtime by the workflow using outputs (e.g. HTTP response code of a HTTP request).

Here are the different Steps we support:

Send an SMS :

SMS step allows you to send a message to a recipient as a SMS.

{
    "id": "step1",
    "stepType": "SMS",
    "inputs": {
        "subAccountId": "Test_12345_ChatApps",
        "destination": "+6512345678",
        "text": "Hello, world!"
    },
    "outputs": {
        "smsRequestId": "{{step.requestId}}",
        "smsUmid": "{{step.umid}}",
        "smsStatus": "{{step.status}}",
        "smsDescription": "{{step.description}}"
    },
    "nextStepId": "step2"
}

‎
Send a Chat Apps message :

ChatAppsMessage step allows you to send a message using 8x8 Chat Apps messaging API.

{
    "id": "step1",
    "stepType": "ChatAppsMessage",
    "inputs": {
        "subAccountId": "Test_12345_ChatApps",
        "user": {
            "msisdn": "+6512345678"
        },
        "type": "text",
        "content": {
            "text": "Hello, World!",
            "sms": {
                "encoding": "AUTO",
                "source": "SENDERID"
            }
        }
    },
    "outputs": {
        "requestId": "{{step.requestId}}",
        "requestUmid": "{{step.umid}}",
        "requestStatus": "{{step.status}}",
        "requestDescription": "{{step.description}}"
    },
    "nextStepId": "step2"
}

‎
Make a HTTP request :

HttpRequest step allows you to make a custom HTTP request and consume its response. For HTTP requests with request data, automation currently supports application/json content type. Automation service will evaluate the dynamic request data at runtime, serialise the input body to json before sending the request.

{
    "id": "step1",
    "stepType": "HttpRequest",
    "inputs": {
        "url": "https://sample.api.com/newrecord/",
        "method": "POST",
        "headers": {
            "Authorization": "Bearer 4ff3987hf934hf3895b469dc0"
        },
        "body": {
           "property_1": 1,
           "property_2": "{{'umid: ' + data.umid}}", // dynamic field using javascript.
           "property_3": "{{data.receivedAt}}", // datetime field.
           "property_4": {
               "nested_property": "{{'msisdn: ' + data.source}}"
           } // Nested field.
          }
        },
    "outputs": {
        "httpCode": "{{step.responseCode}}",
        "httpReasonPhrase": "{{step.reasonPhrase}}",
        "httpResponse": "{{step.responseBody}}"
    },
    "nextStepId": "step2"
}

‎
Set a delay :

Wait step allows you to make the workflow wait for a specified period of time before executing the next step. For example, you might have a workflow triggered by an incoming message received outside of office hours and you may want to make the workflow wait till office hours to send an automatic reply.

{
    "id": "step1",
    "stepType": "Wait",
    "inputs": {
        "minutes": 1
    },
    "nextStepId": "step2"
}

‎
If condition :

The if condition allows you to create multiple paths in a workflow. While you can use Branch step with just one branch to create an if condition, If step allows you to specify a conditional path more easily if you don't need complex branching.
In the below example, the two new properties for If are do and inputs.condition. If the inputs.condition evaluates to true, all the steps specified inside do will be executed.

{
		"id": "step1",
		"stepType": "If",
		"inputs": {
                "condition": "{{!isTimeOfDayBetween(data.payload.status.timestamp, '08:00:00', '17:00:00', 'Singapore Standard Time')}}"
		},
		"do": [
        [
            {
                "stepType": "HttpRequest",
                "id": "call_webhook",
                "nextStepId": "send_ca",
                "inputs": {
                    "url": "http://localhost:8080/mock",
                    "method": "GET"
                }
            },
            {
                "stepType": "ChatAppsMessage",
                "id": "send_ca",
                "inputs": {
                    "subAccountId": "integration_test_automation_chatapps",
                    "user": {
                        "msisdn": "{{data.payload.user.msisdn}}"
                    },
                    "type": "text",
                    "content": {
                        "text": "Hello, world!"
                    }
                }
            }
        ]
    ]
}

‎

Branches

A branch is a specific type of step, allowing you to split your workflow definition, based on a condition.
Here is an example of branch:

{
    "id": "step_1",
    "stepType": "Branch",
    "selectNextStep": {
        "branch1": "{{isCountryCode(data.payload.user.msisdn, 'SG')}}",
        "branch2": "{{isCountryCode(data.payload.user.msisdn, 'US')}}",
        "branch3": null
    }
}

As you can see, the stepType is Branch.

In this case, you need to define the next steps and the condition.
This can be done using selectNextStep and by listing the branches.
You can use any branch name (here we used the names branch1, branch2 and branch3).

The branch names defined here will be used as the step id for the following steps.
In the example above the next step will start with "id": "branch1",

Inside each branch, you need to define a condition, for more detail, see the Scripting section below.

In the example above, we are creating the following logic:

• branch1 will be selected if the source number has a Singapore country code
• branch2 will be selected if the source number has a US country code
• branch3 will be selected otherwise

‎
‎

Context

Workflow context captures the scope in which a workflow is run. Workflow context persists data between steps that you can read from or write to at runtime. Workflow context exposes two state variables data and step. data is where all workflow-level data is stored. step is where all the step-level data is stored. When the step has completed execution, step data is automatically cleared. So, if you want to capture data from a step to use at a later time, you need to save it to data. You can interact with the workflow context using the inputs and outputs in the step definitions.

Suppose you have a property in a step A called status which you want to use in a branch step later on. In order for the branch step to access this value, you need to output the value from step A to workflow context like

{
  "outputs": {
    "custom_status": "{{step.status}}"
  }
}

Now, your workflow data has a property named custom_status that you access from any other step like

{
  "selectNextStep": {
    "branchA": "{{data.custom_status == 'OK'}}",
    "branchB": null
  }
}

data can store complex objects. For example, a workflow triggered by an outbound message may have nested properties like

{
  "payload": {
    "status": {
      "code": 1001
    }
  }
}

and you can access this object in your workflow context like data.payload.status.code.

‎

Scripting

Automation service has rich support for scripting with JavaScript (currently supports ECMA 5.1) via input and output pipelines in the workflow context like member access operators (data.member, data['test']['key']), binary and tertiary operators like x == y ? 1 : 0; and the following functions we have defined for you.

• Check country code of a phone number using isCountryCode(phoneNumber, countryCode). For example, isCountryCode('+6512345678', 'SG') evaluates to true.

• Check if text contains a substring using stringContains(source, value). For example, stringContains('hello, world!', 'wor') evaluates to true.

• Check if a timestamp falls within some time of the day for the specified time zone using isTimeOfDayBetween(timestamp, timeFrom, timeTo, timezone). For example, isTimeOfDayBetween('2020-10-15T14:40:15+07:00', ‘09:00:00', ‘18:00:00’, 'Singapore Standard Time’) evaluates to true. Refer to Time Zones resource for supported timezones.
  To check if a timestamp falls outside a specific time interval you can either specify it as two time intervals chained with an || (logical OR) condition or a negation ! (logical NOT) on a single time interval. For example, !isTimeOfDayBetween('2020-10-15T14:40:15+07:00', ‘09:00:00', ‘18:00:00’, 'Singapore Standard Time’) is logically equivalent to isTimeOfDayBetween('2020-10-15T14:40:15+07:00', ‘00:00:00', ‘08:59:59’, 'Singapore Standard Time’) || isTimeOfDayBetween('2020-10-15T14:40:15+07:00', ‘18:00:01', ‘23:59:59’, 'Singapore Standard Time’)
  

Scripts must be enclosed in double curly brackets like {{data.msisdn == 6500000000}}. The preceding statement will access the msisdn property from workflow context at runtime and check that it equals to 6500000000.

Following restrictions are placed on scripts for security reasons:

• Maximum length of scripts is 1000 characters.

• Assignments, allocations and type declarations are forbidden.

• Maximum number of statements allowed is set to 1 (configurable).

• Recursive functions are forbidden (configurable).

• Scripts that take more than 500 milliseconds to execute are forbidden (configurable).

‎

Time Zones

Certain date and time functions (in scripting) requires you to specify the timezone using a timezone id. You can get the supported time zone ids using the following request. You can use the optional parameter contains to filter timezones whose name contains the specified value.

curl --location --request GET 'https://automation.8x8.com/api/v1/accounts/:accountId/steps/timezones?contains=europe' \
--header 'Authorization: Bearer {apiKey}'

‎If the request is successful, you will get the HTTP status code 200 with the following response body:

[
    {
        "id": "Central Europe Standard Time",
        "name": "Belgrade, Bratislava, Budapest, Ljubljana, Prague (UTC+01:00)"
    },
    {
        "id": "Central European Standard Time",
        "name": "Sarajevo, Skopje, Warsaw, Zagreb (UTC+01:00)"
    },
    {
        "id": "E. Europe Standard Time",
        "name": "Chisinau (UTC+02:00)"
    },
    {
        "id": "W. Europe Standard Time",
        "name": "Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna (UTC+01:00)"
    }
]

‎

Onboarding

To get access to this service, you will need your CPaaS account to be enabled for the Automation API.
Please reach out to your account manager to get this done.

For the events to be sent to the Automation service, you don't need to change your webhooks. We will enable the Customer Integration on your account, for the events to be sent to the Automation service.

You can still continue to manage your webhooks as usual and you will still receive the events.

‎

Examples

Chat Apps auto reply:

{
        "subAccountId": "Test_12345_ChatApps",
        "trigger": "inbound_chat_apps",
        "definition": {
            "name": "Auto Reply ChatApps",
            "steps": [
                {
                    "id": "send_CA",
                    "stepType": "ChatAppsMessage",
                    "inputs": {
                        "subAccountId": "Test_12345_ChatApps",
                        "user": {
                            "msisdn": "{{data.payload.user.msisdn}}"
                        },
                        "type": "text",
                        "content": {
                            "text": "Hello, thank you for your message!"
                        }
                    }
                }
            ]
        }
    }

SMS auto reply:

{
        "subAccountId": "Test_12345_hq",
        "trigger": "inbound_sms",
        "definition": {
            "name": "Auto Reply SMS",
            "steps": [
                {
                    "id": "send_sms",
                    "stepType": "SMS",
                    "inputs": {
                        "subAccountId": "Test_12345_hq",
                        "source": "MyBrand",
                        "destination": "{{data.payload.user.msisdn}}",
                        "text": "Hello, thank you for your message!",
                        "encoding": "Auto"
                    }
                }
            ]
        }
    }

Out of Office with country branch:

{
        "subAccountId": "Test_12345_hq",
        "trigger": "inbound_chat_apps",
        "definition": {
            "name": "Out of Office",
            "steps": [
                {
                "id": "branch_on_msg_country",
                "stepType": "Branch",
                "selectNextStep": {
                    "message_from_ID": "{{isCountryCode(data.payload.user.msisdn, 'ID')}}",
                    "message_from_US": "{{isCountryCode(data.payload.user.msisdn, 'US')}}",
                    "handle_mo_from_others": null
              	 		 }
                },
                {
                "id": "message_from_ID",
                "stepType": "If",
                "inputs": {
                "condition": "{{!isTimeOfDayBetween(data.timestamp, '09:00:00', '18:00:00', 'SE Asia Standard Time')}}"
                },
                "do": [
                	[
                		{
                "id": "ID_out_of_office_hours",
                "stepType": "ChatAppsMessage",
                        "inputs": {
                        "subAccountId": "Test_12345_ChatApps",
                        "user": {
                            "msisdn": "{{data.payload.user.msisdn}}"
                        },
                        "type": "text",
                        "content": {
                            "text": "Halo, terima kasih atas pesan Anda!"
                        }
                    }
                  ]
                 ]
                },
                {
                "id": "message_from_US",
                "stepType": "If",
                "inputs": {
                "condition": "{{!isTimeOfDayBetween(data.timestamp, '09:00:00', '18:00:00', 'Pacific Standard Time')}}"
                },
                "do": [
                	[
                		{
                "id": "ID_out_of_office_hours",
                "stepType": "ChatAppsMessage",
                        "inputs": {
                        "subAccountId": "Test_12345_ChatApps",
                        "user": {
                            "msisdn": "{{data.payload.user.msisdn}}"
                        },
                        "type": "text",
                        "content": {
                            "text": "Hello, thank you for your message!"
                        }
                      }
                   ]
                 ]
               }
            ]
        }
    }

Keyword detection:

{
        "subAccountId": "Test_12345_hq",
        "trigger": "inbound_sms",
        "definition": {
            "name": "Promo_register",
            "steps": [
                {
                    "id": "keyword",
                    "stepType": "branch",
                    "selectNextStep": {
                    		"register_flow_1": "{{stringContains(data.payload.body, 'Register')}}",
                    		"others": null
                    		}

                },
                {
                    "id": "register_flow_1",
                    "stepType": "HttpRequest",
                    "inputs": {
                    		"url": "https://sample.api.com/newrecord/",
                    		"method": "POST",
                    		"headers": {
                    		"Authorization": "Bearer 4f5b6f29654s36654xsvdc895b469dc0"
                           	 },
                    		"body": { 
                    			"register": 1,
                    			"user": "{{'umid: ' + data.payload.user.msisdn}}", 
                    			"time": "{{data.receivedAt}}"
                           	 },
                    		"outputs": {
                    		"httpCode": "{{step.responseCode}}"
                           	 },
                    {
                    "selectNextStep": {
                    	"register_flow_2": "{{step.responseCode == '200'}}",
                    	"register_flow_fail": null
                    	}
                    }
                },
                {
                "id": "register_flow_2",
                "stepType": "ChatAppsMessage",
                "inputs": {
                        "subAccountId": "Test_12345_ChatApps",
                        "user": {
                            "msisdn": "{{data.payload.user.msisdn}}"
                        },
                        "type": "text",
                        "content": {
                            "text": "Hello, you are now registered, thanks !"
                        }
                    }
                },
                {
                "id": "register_flow_fail",
                "stepType": "ChatAppsMessage",
                "inputs": {
                        "subAccountId": "Test_12345_ChatApps",
                        "user": {
                            "msisdn": "{{data.payload.user.msisdn}}"
                        },
                        "type": "text",
                        "content": {
                            "text": "Hello, something went wrong, please try again later"
                        }
                    }
                }
            ]
        }
    }