Inbound Requests with App APIs

When configuring App APIs, you can manage the events that occur when an inbound request comes in. For example, if an App API receives a request, that request can be handled through the API event, which can trigger a Data Flow, start a chat/voice bot, or any other Action. This is useful because it allows you to handle the data from the API request however it is needed, and that data can be used throughout the Journey.

This section will cover how to handle an inbound API request and store that data into AirData. Prerequisites include the following:

• An API has been created in Airkit
• An App Object has been created in AirData with the following properties: id, first_name, last_name
• User understands Data Flows

Create the App API

For this example, the App API will be configured as a POST request and the request body will look like the following:

{  
  "id": "1001",  
  "first_name": "Michael",  
  "last_name": "Scott"  
}

This will be placed in the request body under the Sample URL, which is used to create a sample payload. When clicking the 'Play' icon, this will generate a sample payload that can then be accessed through the 'payload' namespace.

For information on how to create an App API, validation, mapping, and response codes, see Creating an API for your Airkit App. 

Mapping the Request to a Journey Event

In order to map the API request to the journey, there are two approaches - passing the request to session.start or passing it to the journey event. This example will show how to pass the request body to the event namespace, but you can easily pass it to session.start by passing the payload to the 'Start Parameters' under the Mapping section of the API configuration. For further reading, Creating an API for your Airkit App includes a breakdown of each of the Mapping properties. 

Under the Mapping section, enter payload.body under Journey Event Payload. This will surface the request body in the API request handler event and allow you to access the id, first_name, and last_name from the payload. 

Creating the Data Flow to pass the request to AirData

Once the API is set up, a Data Flow will need to be created to pass the request body to an App Object in AirData. The Data Flow created for this example will need to capture the id, first_name, and last_name and then write that to AirData.

Create a Data Flow and name it 'Insert User Object'. Add three text input variables. The request properties will be passed into the data flow inputs. 

Then add the AirData data operation, select the App Object that you want to store the values to, and change the Type to PUT. Then in Objects to insert or update, add:

[  
  {  
   "id":id,  
   "first_name":first_name,  
   "last_name":last_name  
  }  
]

The object service Data Operation should look like the image below:

Running the Data Flow in the API event

Every API created in Airkit has an event associated with it. In the event, you have the option to run many different actions when that API endpoint receives a request. To add actions to the event, go to Journey Builder > Integrations > App API > Select the API you created > Go to the Actions tab in the inspector. 

Go to App > Add the Run Data Flow action and select the Data Flow created in the previous step. In the inputs, enter in the following:

• id: event.id
• first_name: event.first_name
• last_name: event.last_name

Using the event namespace, you can access the data that was passed to the Journey Event Payload in the previous Mapping step. 

Now the application is set up to receive a POST request and will write the request body back to AirData. 

Additional Use Cases

An inbound API can be used to trigger many different actions within Airkit. One use case, is to use that inbound API to initiate a chat conversation via SMS from an external system. For example, for tracking statuses, an external system can be used to call the inbound API to initiate a journey that sends an update to that user about their status being updated or changed. They can then be sent a 'canvas link' to view more details for what is being tracked within that SMS as well. 

Another use for an inbound API is to use it to change or update a web page on an existing session. For example, an inbound API can be mapped to an existing session and when an external system makes a request to that API, it can trigger an update to that user's session and take them to a new view. For example, this is useful for waiting on an external system to verify information of a user and will make a request back to the application once it is done verifying.

Inbound Requests with Subscriptions (web hooks)

Understanding Subscription and Events

Subscriptions (webhooks) are a mechanism to send data when triggered by an event in an application. Within an Airkit application, you can set up subscriptions with the Airkit's first party integrations such as Twilio, Zendesk, Salesforce, Google, and Stripe. For example if you use the Salesforce Subscription, you can start a journey when a the status of a lead is updated or if a record is created. 

Setting up a Subscription

In this example, we'll be setting up a subscription to Salesforce whenever a Lead is added.

1. Before creating a subscription, set up a connection to Salesforce and then add the integration to your Airkit Application. Once connected, go to Configuration Builderand add the Salesforce adapter in Integrations. Click on +New and then Adapters, and select Salesforce.

2. Select the Credential associated with Salesforce that you would like to use and Save. This will enable your app to use the Salesforce integrations when creating a Subscription. 

3. Go to Connection Builder and click on '+' to add a Salesforce subscription. 

4. Select a webhook category. For this example, we'll be starting a journey when a new record is added. 

5. Choose an Object Type. This example will be using the Lead object type. 

After selecting the Object Type, you can define what happens after a lead is added by configuring the journey mapping.

Configuring the Journey Mapping

If you have created an API for your Airkit App, then the journey mapping configuration may look familiar. 

Sample Payload

This is a sample so you can use to know how to build your request. After expanding the Sample Payload, you can hit the Play button to see what that payload would look like. 

Mapping
The mapping section is where you can specify what happens once your subscription receives an event. For example, when a lead gets added into salesforce, you can:

• Start a new journey
• Replace a current journey
• Abort a journey if a match is found
• Lookup and use an existing journey

Start Parameters

Start parameters is where you can pass any type of data that is available from your subscription to the journey to session.start. Start parameters are only applicable when your Journey Behavior is 'Start or Create a new Journey'. 

session.start

Journey Identifier Expression

The journey identifier expression is where you can map an identifier on a session from a piece of data out of the payload or connection namespace. For example, if there was a specific Salesforce ID that came out of the request payload, you could then use that Salesforce ID as the journey identifier. You are given the options of what type the identifier is as well -- Text, Journey ID, or Phone. 

Journey Event PayloadJourney event payload is where you can pass data from your subscription into the event namespace.

For example, if you pass

payload.result

into the Journey event payload, then on your subscription event, you can access the data via

event.property_name

Response
This is where you can define what your subscription will return after the actions are executed. 

Response Status is where you can perform validation using Airscript to have your subscription return a particular response status code. This example checks to see if the Phone property is empty, and returns a 200 if it is not empty. 

Response Body is the response from the subscription. The response body accepts data from the metadata, payload, and connection namespace. 

How Publishing an App subscribes and unsubscribes from an external web hook

When publishing an app, the subscription (web hook) is set on the external system. So when creating the subscription, the subscription has not actually been registered yet until the app has been published. Alternatively, when the app is unpublished, the web hook is unset from the external system.