External API
This document explains the simplified ways to configure External APIs and create engagement.
External API facilitates you to connect with multiple third-party APIs allowing you to integrate with any third-party service like a CRM, IVR, Private ESP/SSP, etc. to automate your engagements.
Use cases for External API
CRM: Integrate with CRM like Hubspot, Vymo, etc.
IVR: Integrate IVR services to automate communication for immediate responses
Private ESP/SSP: Integrate your own email or SMS service providers to create engagement to ensure the confidentiality and privacy of your PII data through data encryption.
Email Service Provider (ESP): Integrate with email service providers like mailmodo, etc.
Facebook Conversion API/ Google Conversion API: Integrate Facebook and Google conversion API to send conversion data from CDP to Google and Facebook
Internal system API: Pass data from the CDP to internal APIs in services like Banking financial services and insurance which will have confidential APIs used internally for their service operations.
Lead submission API: Submit the data captured from WhatsApp or any other lead forms into your lead management system
Prerequisite
API Docs / API reference docs
Valid authorization scheme and keys: Depending on your free/paid account with your external system, OR your internal tech implementation of the API, you should have the relevant authorization mechanism and its keys/passwords/tokens handy. Your POC from the external vendor or your tech team shall help you with the same
Steps to Configure an External API
Go to > Campaigns > Channels > External API
Step 1: Click the +Add New External API Button
Step 2: Add Basic Details
Name: Name your External API. This name cannot be editable once it is saved.
Description: Enter the description of your API.
Channel: Choose the channel in which you want the API to communicate with your audience. Lemnisk provides Email and SMS channels for the API to communicate.
Step 3: Add External API Details
HTTP Method: Select the necessary HTTP method from the dropdown. Supported methods: GET, POST, PATCH, PUT, and DELETE.
URL: Add the endpoint URL of your API and enter the variable for path parameters (if any).
URL Path parameters are variable parts of a URL path that are used to point to a specific resource within a collection
Adding dynamic path parameters in the URL:
If you have a path parameter that will change each time you trigger an engagement, you can configure it dynamically by defining the variable in {{variable}}. Here's an example to do it:
{{Campaign_ID}} is the URL path parameter we declared above and added a default value.
The parameters we add to this variable will be reflected while adding the engagement which can be changed later.
Headers: Add Headers to provide the metadata about the request.
Common headers that are used while making requests:
Accept
Content-Type
Content-length
Authorization ( use the necessary authorization keys which may vary according to the APIs)
User-Agent
Cache-Control
Connection
Query Parameter:
Query parameters are the key-value pairs provided at the end of the URL which gives additional information to the webserver while making the request.
Payload: Paste the payload in the black code edit screen as shown below. You can set the payload to None if the API doesn't have any request body. GET requests will not have any payload however POST APIs may have the payload associated with the API.
Sample Payload:
You can set the payload at 2 levels.
Global Level: In the Global Level, you define the payload for the API. To define the payload, just enter the JSON payload in the code block. Please ensure that it should be a valid JSON. For invalid JSON, an error will be shown in the UI. If the given payload is correct, it will deploy a tree view. you can add static or dynamic fields, create variables, and add the display term flexibly using the tree formation that enables you to assign values to the parameters based on parent and child objects.
The payload you entered will be displayed in the following tree view.
( This payload is custom-made for demonstration purposes)
To Configure the parameters in engagement level, pass the variable between double curly braces i.e., {{variable_name}}.
Enter the display name which will be shown on the UI as the variable alias, when you're creating engagements for the configured API.
Enter the default value that assigns value to the parameter by default if the value is not provided by the user, or in the case of Macro when the system fails to replace it with a value.
Optional Field:
If you wish the field to be mandatory, select No.
Select Yes, if the field needs to be optional. In such a case, you have to define how to handle the payload when that particular key (param1 in the example) is not provided with a value.
Option 1: Send Empty Value (do nothing)
The parameters will be empty, and the default value will be shown here in all the engagements.
The payload will be:
Option 2: Drop details.data (Parent Node)
On Choosing drop details. data, the parent node (Data) will be dropped. The grandparent node (details) and ( Token) will be considered as objects.
The payload will be:
Option 3: Drop details (Grandparent Node)
On Choosing drop details, the grandparent parent node (Data) will be dropped along with its child ( Data). Only (Token) will be considered as objects.
Option 4: Drop the whole Object
On choosing to drop the whole object, the entire payload will be dropped and the API won't get triggered.
Engagement Level:
The engagement level payload feature allows users to set a specific payload while creating an engagement instead of defining it at the global level. This flexibility is particularly beneficial when running campaigns with varying payload requirements. By utilizing the engagement level payload, users gain the liberty to send any customized payload when setting up engagements. This feature proves to be highly useful when integrating with external platforms like Mailmodo, where the payload may need to change from one campaign to another. Please note that at this time, our platform exclusively supports JSON payload at the engagement level.
Last updated
