Summary

Botdoc Automations are designed to perform automated calls to the API endpoints itself based on custom triggers that can be set in the Automation configuration.

In order to use Automations, you still need to have a comprehensive understanding of how the API works, as in order to configure Automations and, the flows you can create with it.

When working with Automations, you should be familiar with its 3 components; those are:

Automation Group: Defines a group of ordered Automation(s) (or so-called actions) to be performed.
Automations: Defines a single action to perform.
Triggers: Defines “when” the AutomationGroup should be executed according to the available Triggers created.

Context

Automation has its own context. Each Automation (step) and Trigger exports a different set of variables in order to be used between each of the steps as needed. This is important as in most of the scenarios, you will need data from the creation of a Container in order to associate a Recipient to that Container and so forth. The context gets updated after the execution of each step, containing new data returned by the current step being executed. The context available in the current step being created is all of the previous steps and the trigger variables. Trigger variables are defined by the trigger type being used. See tables below to understand the variables available in each of the trigger types.

Context scheme

{
  "trigger": {
    "<trigger_slug>": {
      "trigger_attribute" : "trigger_value"
    }
   },
  "automations": {
    "<automation1_slug>": {
      "endpoint_response_index": "endpoint_response_value",
      ... other attributes the endpoint returned...
    },
    "<automation2_slug>": {
      "endpoint_response_index": "endpoint_response_value",
      ... other attributes the endpoint returned...
    },
    (...)
}

Trigger Contexts scheme

Inbound Text from URL Trigger

This trigger creates a unique URL of which when opened by someone, it will try to open the native SMS app on the users phone with a default message. This trigger will then wait for a text message with the reference # created by the trigger in order to execute the Automation Group this trigger is associated with. The reference numbers created by this trigger do expire; this means the time between opening the URL and sending the message should NOT exceed10 minutes; otherwise the reference # created for that trigger is expired and won’t trigger the Automation Group.

Attribute	Description

Attribute	Description
origin	Contains the mobile phone number from the sender of the message
reference	Contains the reference # sent over the SMS message
remote_addr	Contains the user IP that triggered the session
*	This is a wildcard as this Trigger has the capability of receiving query arguments on its trigger URL. For each variable found in the query args, a new variable will be added to the trigger context with its value.

Hands on

We will walk you through the creation of an automation, showing step by step how to create an Automation.

Creating an Automation Group

First, login to your developer portal and navigate to “Automations => Automations”. On this page you should see a list of all Automation Groups created for the selected Apikey. Click on the plus button in order to add a new Automation Group. You should see the following screen. In this first step you need to enter a name and click save.

Once saved, the page will allow you to make additional changes to the page, such as adding Triggers and Steps.

Create a Trigger

The first step now is to create a Trigger, that defines when this Automation Group will be executed. Click on the “Select a trigger to add”, choose the type of trigger you want and click ADD. In this case we will choose Inbound Text from the URL Trigger.

Here, we gave a Label to the trigger, a slug, a default message that is the message that will be pre-filled on the user mobile and, selected the number we expect a message back from the pool of numbers available. (The URL trigger is only shown after you save the trigger)

This trigger as its configured will open the Message application on the mobile device once the Mobile device visits the page that is configured under URL trigger, with a pre-filled body of “Hello there, I need to send my documents to you” to the number selected under “Inbound number”.

This trigger also creates some new variables to use in the Context of this Automation Group. The context up to this point in the example looks like:

{
	"trigger": {
		"trigger1": {
			"origin": <number from whom sent the message>,
			"remote_addr": <ip address of who opened the url>,
			"reference": <reference created by the trigger number>
		}
	}
}

We could still add more query arguments to the URL before actually giving it to someone. For example, let’s say we want to distribute this URL to the State but, we want to know the City that URL was opened. We could in this case send the URL

https://<base_url>/v1/module_automations/p/trigger1/X/trigger/?city=Aurora

to the people in Aurora-CO and

to the people in Denver. This small change will cause the associated variables for the trigger to change. The context for the URL opened from Aurora would look like:

While for the people who open the URL from Denver, it would look like:

A word of caution: You should NOT use the reference # generated by a trigger as a unique id. This reference is randomly generated, and its uniqueness is not defined by its value only.

Create Automation(s)

Now we move on to the Automation(s) of this Automation Group. These steps will define what the Automation Group will actually do. For example, we will want to reproduce the following flow:

Create a P2 Container
Create a default message inside that P2 Container saying “Hello there! To get started, enter your full name”
Create a Recipient for that Container
Create a RecipientItem for the step 3 Recipient created with the mobile number we received the text from
Create a ContainerMetadata to this Container with the City
Send the Container

In order to add steps, select an Automation type under “Select automation to add” and click on ADD button. This example will use API Http Call automations.

Create Container Automation

According to the flow we want, the first step is to create a P2 Container.

Create a Message

Now, we will move forward and create a Message in that Container, in order to do so we add a new step and:

According to our API documentation, when creating a Message, I must also provide what is the Container I want to associate that message to. That is another usage of the Context. As the creation of the Container comes prior to the creation of the Message, the data returned by the endpoint for creating a Container in step 1 is available for use in step 2. This is valid for all steps through the whole set of steps defined in the Automation Group; any data returned on a prior step will be available on the current step accessing the Context variables.

In step two, our context looks like:

The createContainer step has exactly what the data our API returns for the creation of a Container, it can be used in further steps.

Create a recipient

Now we move ahead to the next step, which is creating a Recipient, this step is defined as:

As the step 2, in order to create a Recipient we need to know what Container it belongs to; therefore we access our Context data in order to get the container id created on step 1.

Create a RecipientItem

Now we need to associate a RecipientItem to the Container. That's how and where we will send that container. As we are using the Inbound Text from URL Trigger, the users mobile number is available to us in the Context. So, we will pull that number and, send as a text message.

Create ContainerMetadata with the City

We are almost done, we just need to grab the Query Argument in the URL “city” and associate that with the Container as ContainerMetadata, so when you pull the Container information from our endpoint, you will know the City of the User that created that Container, for example.

Send the Container

Now we just need to send that Container. In order to do so we just need to call the send notification endpoint in our API.

If you notice, in this last step we are also using the context as we need to know the Container we want to send. We can also use context variables in the API Relative Path field and, they will be replaced according to its value. In this case we are again pulling the Container all the way from step 1.

Conclusion

This concludes a very simple Automation flow that will send a Container to a user that opens the URL of the trigger and, starts a conversation. From here, there are thousands of different flows and use cases that are possible. As soon as the container is sent and opened, our API triggers several Webhooks to the provided URL (if this would have a callback, it would be in the Container definition in step 1). From there you can automatically pop notifications and, start conversations from with in your integration with us.

A common use case with this URL trigger is actually embedding the URL as a QR code, which users will be able to scan and, open the text message automatically after scanning. You could include different Metadata (URL query args) and, distribute differently.

There are hundreds of use cases this allows you to create. Now, get creative and let us know what is the next awesome project you will work on using this Feature.

Botdoc Service Desk

(API) - Automations