Concept: Activity

Activity Sync is a feature within Pendula that emits real-time events when specific actions or state changes occur during a flow. We call these events activities; as they represent activities such as when a message is queued, delivered, or when an experience (a unique interaction with a flow) starts or finishes. You can learn more about activity here.

Activity Sync allows external systems to subscribe to or consume these activities in order to monitor, report on, or trigger actions based on recipient interactions within a flow. Essentially, it provides a way to track and respond to the lifecycle of recipient interactions as they move through a flow, creating opportunities for automation, detailed reporting, and troubleshooting.

Key uses:

• Real-time monitoring: Systems can capture live activity data, such as message delivery, bounces, or other events, and act immediately.
• Reporting: By consuming activities, you can generate reports on flow performance, message success rates, and engagement rates.

To see Activity Sync in action, please visit this article.

Concept: Activity
Concept: Activity Sync

What this document covers:

• What are the types of activity: Learn about the various types of activities that Pendula emits, including messaging, experience lifecycle activity, and inbound message matching.
• How activities are structured: Each activity is provided in a structured JSON format, which includes contextual data like the flow, experience, and additional custom information.
• How to use these activities: These activities can be consumed by third-party systems for monitoring, reporting, or alerting purposes. By understanding the structure of each activity, you can create meaningful insights or automate actions based on them.

Workflow context

For every activity, there is what’s called workflowContext (object). The workflowContext object contains all the relevant contextual information for that activity:

• The associated experience (experienceContext: experienceID)
• The associated flow (flowContext: flowId, flowName, flowVersion)
• The associated node within the flow (nodeContext: nodeId, nodeName, outputName)

While all activities include workflowContext, some are not fully populated yet (Inbound message unmatched, inbound message trigger). We are working to implement workflowContext consistently for all activities.

"workflowContext": {
"experienceContext": {
"experienceId": "501b95b3-06d3-4398-9ad4-b2563e158308"
},
"flowContext": {
"flowId": "b07a5e44-04e3-4698-a799-04c558b77147",
"flowName": "My first flow",
"flowVersion": 2
},
"nodeContext": {
"nodeId": "node-e72ur",
"nodeName": "Upsell Conversation",
"outputName": "conversation_2"
}

Custom context

Custom context consists of a set of configurable key-value pairs that can be added to all activities for experiences. To learn more about custom context in depth and how to use it, please visit this article.

Experience activity

experience-start

The very first activity for an experience is an experience-start activity:

{
"experienceId": "60b34d82-7781-474b-ad10-4bca1a774e14",
"timestamp": "2024-08-27T13:25:04.913Z",
"workflowContext": {...},
"customContext": {},
"kind": "experience-start"
}

experience-finish (outcome: success)

Here is a successful, ‘Complete’ experience-finish activity:

{
"experienceId": "60b34d82-7781-474b-ad10-4bca1a774e14",
"timestamp": "2024-08-28T13:40:13.482Z",
"outcome": {
"success": {
"value": {}
}
},
"workflowContext": {...},
"customContext": {},
"kind": "experience-finish"
}

experience-finish (outcome: failure)

Here is a failed, ‘Failed’ experience-finish activity. Before this activity, there may be other activities signalling what caused the experience to fail and finish (for instance, validation-failed for a message or bounce)

{
"experienceId": "60b34d82-7781-474b-ad10-4bca1a774e14",
"timestamp": "2024-08-28T14:12:52.134Z",
"outcome": {
"failure": {
"errorMessage": "Unhandled outcome for messaging/sendSenderIdSmsWithOutcome: failure/validation-error. Context: {\\"rawArgs\\":{\\"message\\":{\\"kind\\":\\"handlebars\\",\\"handlebars\\":\\"Activity Sync - Unmatched Trigger node - SENT outcome\\"},\\"senderId\\":{\\"kind\\":\\"handlebars\\",\\"handlebars\\":\\"PENDULA_TEST\\"},\\"recipientNumber\\":{\\"kind\\":\\"handlebars\\",\\"handlebars\\":\\"{{ unmatchedMessageTrigger_1.fromNumber }}\\"},\\"successTimeoutMins\\":{\\"kind\\":\\"number\\",\\"number\\":1}},\\"outputs\\":{\\"outcome\\":\\"failure\\",\\"outcomeReason\\":\\"validation-error\\",\\"timestamp\\":1724854371406},\\"args\\":{\\"message\\":\\"Activity Sync - Unmatched Trigger node - SENT outcome\\",\\"senderId\\":\\"PENDULA_TEST\\",\\"recipientNumber\\":\\"+61401260405\\",\\"successTimeoutMins\\":1},\\"type\\":\\"messaging/sendSenderIdSmsWithOutcome\\",\\"nodeId\\":\\"node-g2zkv\\"}",
"errorCode": "experiences/fail"
}
},
"workflowContext": {...},
"customContext": {},
"kind": "experience-finish"
}

experience-failed

And finally, here is an ‘Error’ experience-failed activity. If multiple of these activities are detected within a flow; the flow itself will be stopped and also set to status ‘Error’.

{
"experienceId": "ee4ee007-2bb2-41de-8da3-038cfe33564d",
"timestamp": "2024-09-04T00:05:23.443Z",
"workflowContext": {...},
"customContext": {},
"errorDetails": [
{
"errorMessage": "Not found: inboundWebhookTrigger_1 (full path: inboundWebhookTrigger_1.message). Available fields were: AvailableFields[inboundSMSTrigger_1.fromNumber:<+.10.5>,inboundSMSTrigger_1.matchedIntent:<m.8.d>,inboundSMSTrigger_1.matchedPart:<M.8.d>,inboundSMSTrigger_1.matchedType:<E.19.)>,inboundSMSTrigger_1.messageBody:<M.8.d>,inboundSMSTrigger_1.timestamp:<number>]",
"errorCode": null
}
],
"kind": "experience-failed"
}

Messaging events

A message being ‘queued’ is the first activity in the process of sending a message. The message queued activity contains all of the relevant information for the lifecycle of a message (recipient, message body, attachments etc) and generates a message ID.

Any subsequent activities (sent to gateway, delivered, opened, any failures etc) can all be correlated back to the initial queued activity using the message ID.

queued (SMS)

Here is a message queued activity for an SMS:

{
"messageId": "1d8e4e9c-69d8-4cd1-83fe-c13ef6870cfd",
"payload": {
"sender": "0000000000",
"recipient": "+61412345678",
"body": "Thanks for signing up, John.",
"segmentCount": 1,
"kind": "sms"
},
"timestamp": "2024-08-28T13:38:46.210055990Z",
"workflowContext": {...},
"customContext": {},
"kind": "queued"
}

queued (email)

Here is a message queued activity for an email:

{
  "messageId": "3064433f-d939-4df9-b49b-a2fa2573bce2",
  "payload": {
    "sender": "me@appleseed.com",
    "recipient": "john.smith@bananas.com",
    "subject": "Thanks for registering with us.",
    "body": "<hmtl>\\n <body>\\n Hello world!\\n </body>\\n</hmtl>",
    "plainTextBody": "\\n \\n Hello world!\\n \\n",
    "replyTo": "me@appleseed.com",
    "attachments": [
      {
        "filename": "welcomepack.pdf"
      },
      {
        "filename": "file2.png"
      }
    ],
    "kind": "email"
  },
  "timestamp": "2024-08-29T01:18:25.532229654Z",
  "workflowContext": {...},
  "customContext": {},
  "kind": "queued"
}

sent-to-gateway

Here is a message sent to gateway activity for SMS and email:

{
"messageId": "1d8e4e9c-69d8-4cd1-83fe-c13ef6870cfd",
"timestamp": "2024-08-28T13:38:46.434638837Z",
"workflowContext": {...},
"customContext": {},
"kind": "sent-to-gateway"
}

delivered

Here is a message delivered activity for SMS and email:

{
"messageId": "1d8e4e9c-69d8-4cd1-83fe-c13ef6870cfd",
"timestamp": "2024-08-28T13:38:52.362Z",
"workflowContext": {...},
"customContext": {},
"kind": "delivered"
}

opened

Here is a message opened activity for SMS and email:

{
"messageId": "3064433f-d939-4df9-b49b-a2fa2573bce2",
"timestamp": "2024-08-29T01:19:41.746Z",
"workflowContext": {...},
"customContext": {},
"kind": "opened"
}

bounced

Here is a message bounced activity for SMS and email:

{
"messageId": "ad45e9e3-e0ae-48f9-bdc0-e7c328a10b0b",
"errors": [
{
"errorMessage": "Bad request",
"errorCode": "explanation"
}
],
"timestamp": "2024-08-28T14:01:52.132Z",
"workflowContext": {...},
"customContext": {},
"kind": "bounced"
}

validation-failed

Here is an activity for when a message fails to send due to validation failing:

{
"messageId": "fb1ec07a-42ae-4b90-ae02-5b6cc8f6a2e3",
"errors": [
{
"errorMessage": "NonEmptyList(Recipient must be a valid phone number, got: Beepboop. )",
"errorCode": null
}
],
"timestamp": "2024-09-03T04:29:45.419079448Z",
"workflowContext": {...},
"customContext": {},
"kind": "validation-failed"
}

rejected-by-gateway

{
"messageId": "fb1ec07a-42ae-4b90-ae02-5b6cc8f6a2e3",
"errors": [
{
"errorMessage": "Rejected by gateway.",
"errorCode": null
}
],
"timestamp": "2024-09-03T04:29:45.419079448Z",
"workflowContext": {...},
"customContext": {},
"kind": "rejected-by-gateway"
}

Inbound messages & replies

inbound-matched-intent (trigger)

Here is a message inbound matched trigger activity (this happens after an experience-start activity):

Note that workflowContext is not fully populated: flowName and flowVersion

{
"messageId": "d3703474-8c92-4ee8-acf0-5353407bbc71",
"parentMessageId": "1d8e4e9c-69d8-4cd1-83fe-c13ef6870cfd",
"matchedIntentKey": "optin",
"matchedType": "Rule Match (Trigger)",
"matchedPart": "opt-in",
"body": "I'd like to opt-in",
"fromNumber": "+61412345678",
"timestamp": "2024-09-03T03:48:49.187411Z",
"workflowContext": {
"experienceContext": {
"experienceId": "6c36658f-6017-449e-9f91-3f23e3e9876a"
},
"flowContext": {
"flowId": "7d39b190-71fd-4295-9a48-1285f083de95",
"flowName": "?",
"flowVersion": 0
},
"nodeContext": {...}
},
"flowId": "7d39b190-71fd-4295-9a48-1285f083de95",
"customContext": {},
"kind": "inbound-matched-intent"
}

inbound-matched-intent (reply)

Here is a reply:

{
"messageId": "5ae77323-c8c5-4858-ac35-27798e98d6e9",
"parentMessageId": "e5cebadf-f1bc-4c2b-b892-f7ddd1bb3e59",
"matchedIntentKey": "upgrade",
"matchedType": "Rule Match (Conversation)",
"matchedPart": "upgrade",
"body": "I'd like to upgrade",
"fromNumber": "+61412345678",
"timestamp": "2024-09-03T04:27:52.953530Z",
"workflowContext": {...},
"flowId": "7d39b190-71fd-4295-9a48-1285f083de95",
"customContext": {},
"kind": "inbound-matched-intent"
}

inbound-unmatched

Here is a message inbound unmatched activity (this happens after an experience-start event):

Note that workflowContext is not fully populated: flowID, flowName and flowVersion

{
"messageId": "e46a9bce-f03e-4232-b68c-f27fce70a99f",
"payload": {
"sender": "+61487654321",
"recipient": "+61412345678",
"body": "I need some help",
"kind": "sms"
},
"timestamp": "2024-08-29T01:18:24.792807Z",
"workflowContext": {
"experienceContext": {
"experienceId": "60b34d82-7781-474b-ad10-4bca1a774e14"
},
"flowContext": {
"flowId": "?",
"flowName": "?",
"flowVersion": 0
},
"nodeContext": {...}
},
"customContext": {},
"kind": "inbound-unmatched"
}

Concept: Activity
Webhook trigger: Configuring Pendula with third party apps
Concept: Activity Sync

What is custom context?

Custom context consists of a set of configurable key-value pairs to add additional contextual information to an experience. This is particularly useful when you need to add extra, often correlation-specific, details to experiences that either trigger from or update other systems.

By using custom context, you can trace information from upstream systems, all the way through Pendula, and then to debugging issues across downstream systems in an effective way.

Why and when to use custom context

Custom context can include any key-value pairs you define, making it highly flexible. This document explores one of its potential uses as a "correlation" identifier, which can help you link and track activities across different systems.

We will demonstrate how to add custom context to experiences as part of the inbound webhook payload that triggers a Pendula flow.

Adding custom context to activity using a webhook

To add custom context to experiences triggered by an inbound webhook, include a specific header in your HTTP request:

X-PENDULA-CUSTOM-CONTEXT: {"customKey1": "value1", "customKey2": "value2"}

When making a POST request, you can include the custom context along with your payload. Here’s two different formats of a payload with custom context in the header:

CURL request example

curl -X POST "https://pendula.app/webhook/inbound/12345678-1234-1234-1234-123456789abc" \
-H "Authorization: Bearer {insert token}" \
-H "Content-Type: application/json" \
-H "X-PENDULA-CUSTOM-CONTEXT: {\"customKey1\": \"value1\", \"customKey2\": \"value2\"}" \
-d '{
"user-id": "John Appleseed",
"firstname": "John",
"lastname": "Appleseed",
"mobile": "+61412345678"
}'

Formatted request example

• Method: POST
• URL: https://pendula.app/webhook/inbound/12345678-1234-1234-1234-123456789abc
• Headers:
  • Authorization: Bearer {insert token}
  • Content-Type: application/json
  • X-PENDULA-CUSTOM-CONTEXT: {"customKey1": "value1", "customKey2": "value2"}
• Body: { "user-id": "John Appleseed", "firstname": "John", "lastname": "Appleseed", "mobile": "+61412345678" }

Best practices

• The custom context value must be formatted as a JSON object.
• Properly escape characters in the custom context to avoid parsing issues (if using curl).
• Use a consistent structure for custom context across all your webhook requests to facilitate easier processing and debugging.

Note: If your custom context header is not a valid JSON object, the following error will be returned from Pendula (400):

Custom Context header must be a valid Json Object

Custom context for reporting

Since custom context can easily identify and link experience activity across systems, it can also be used with reporting tools like Activity Sync.

By correlating activity with external systems, you can create a comprehensive view of everything that happens across your systems and in your customer communications down to the individual level.

For more advanced triggers, such as AWS Kinesis, custom context information is captured and logged as part of the event metadata.

Example scenario

Imagine you are using Pendula to:

1. Trigger a customer feedback survey flow with data from your CRM.
2. Send conversational SMS messages that capture customer replies as feedback.
3. Write back the replies and updates to another system of record.

You want to tag all the associated activity with:

• The corresponding customer record in your CRM (a dynamically populated external ID).
• The type of communication (a static value; feedback survey)

By appending the Customer ID from your CRM as externalCustomerID (a dynamic value), and the communication type as communicationType (a static value) as custom context, you can ensure that every activity is tagged appropriately.

Here’s what the inbound payload would look like:

curl -X POST "https://pendula.app/webhook/inbound/12345678-1234-1234-1234-123456789abc" \
-H "Authorization: Bearer {insert token}" \
-H "Content-Type: application/json" \
-H "X-PENDULA-CUSTOM-CONTEXT: {\"externalCustomerID\": \"CABC123DEF456\", \"communicationType\": \"FeedbackSurvey\"}" \
-d '{
"user-id": "John Appleseed",
"firstname": "John",
"lastname": "Appleseed",
"mobile": "+61412345678"
}'

Once the webhook is sent, all experiences will be tagged with the Customer ID as externalCustomerID from your CRM and the communicationType will be 'FeedbackSurvey'.

Example activity

If you want to view the full list of activity examples, please read this article.

Queued SMS Message Activity:

{
"messageId": "*******",
"payload": {
"sender": "0000000000",
"recipient": "+61412345678",
"body": "Thanks for using our product. We'd love to hear about your experience.",
"segmentCount": 1,
"kind": "sms"
},
"timestamp": "2024-08-28T13:38:46.210Z",
"workflowContext": {},
"customContext": {
"externalCustomerId": "CABC123DEF456",
"communicationType": "FeedbackSurvey"
},
"kind": "queued"
}

Inbound Message Activity:

{
"messageId": "*******",
"parentMessageId": "*******",
"matchedIntentKey": "free",
"matchedType": "Rule Match (Conversation)",
"matchedPart": "Loving so far. I'd love to check out the higher tier plans.",
"body": "Loving so far. I'd love to check out the higher tier plans.",
"fromNumber": "+61412345678",
"timestamp": "2024-08-28T14:00:52.953Z",
"workflowContext": {},
"flowId": "7d39b190-71fd-4295-9a48-1285f083de95",
"customContext": {
"externalCustomerId": "CABC123DEF456",
"communicationType": "FeedbackSurvey"
},
"kind": "inbound-matched-intent"
}

Webhook trigger: Setting up an API token

The Webhook Trigger node listens for information in real-time from an external application to trigger a Pendula flow. 

What is a Webhook?

A webhook is a way for an application to automatically exchange real-time data with other applications. It functions as an HTTP request triggered by an event in a source application and sent to a destination application with a data payloadInsert definition here. This allows one application to "speak" to another in real-time, sharing information about the event. For example, a telco provider can use webhook to notify Pendula whenever a new customer activates a service. When the event occurs, the source system (telco provider) sends an HTTP POST request to the destination system (Pendula) with activation details. Upon receiving the payload, the webhook trigger in Pendula initiates an experience, such as sending a welcome message or service confirmation to the customer. This automated communication enables immediate data transfer without manual intervention.

Usage scenario

The following example demonstrates a practical application of the Webhook Trigger within a flow, that sends an onboarding message following a new service subscription. When a user signs up for a new subscription, the source system is configured to send a payload to a webhook URL. Here is an example request body of a payload:

{ 
  "user-id": "harrison-example", 
  "firstname": "harrison", 
  "lastname": "koenig", 
  "mobile": "+61400000000" 
}

Upon receiving a webhook, Pendula triggers an experience designed for new subscribers. This flow could include actions like sending a welcome message, providing important information about the service, or scheduling follow-up interactions.

Configuring this trigger

1. In a new flow, drag and drop the webhook trigger node onto the canvas to open up the settings panel.
   
2. Follow the prompts to set up your API token if you have forgotten it or it hasn't been generated before.
3. Copy the “POST URL” found under Configure Webhook trigger URL. This URL identifies this specific Pendula flow.
4. Paste link as the ‘POST URL’ in the Webhook configuration settings of the third party application.

Learn more about which configuration method should be used.

What is a payload?

A payload is the data sent from one application to another when an event occurs. This data is included in the body of the HTTP request and typically contains detailed information about the event that triggered the webhook. For best practices -

• The request must be in JSON format.
• The minimum recommended payload inclusions are:
  1. First name
  2. Last name
  3. Mobile number
• The payload must be less than 200 KB

Here's an example of how to format your payload:

curl -X POST --location https://{{ Replace with your Pendula domain }}/
webhook/inbound/{{ Replace with ID from flow builder }}
-H "Authorization: Basic {insert token}"
-H "Content-Type: application/json"
    -d "{
        "user-id": "harrison-example",
        "firstname": "harrison",
        "lastname": "koenig",
        "mobile": "+61400000000"
        }"

Validate payloads and use webhook merge fields

To validate your webhook and use the webhook data as merge fields later in the flow, Pendula allows you to paste a sample payload into the Merge fields tab of the webhook trigger node.

Learn more about Pendula and merge fields.

Simply copy the request body of the payload (not including headers) and paste into the sample payload field. The sample payload must be in JSON format (key value pairs with hierarchy)

Here's an example of the request body of the payload above, in JSON format:

{
  "user-id": "harrison-1a2b3c4d",
  "firstname": "harrison",
  "lastname": "koenig",
  "mobile": "+61400000000"
}

Note that any sample properties with 'null' values can't have a type, and sample value, inferred from them. Please only provide sample properties with not-null values.

Possible error responses

Duplicating a flow with a Webhook trigger

When a user duplicates a flow with a Webhook Trigger, the POST URL in the webhook trigger is automatically regenerated.

This means that the new flow has a new address, and you will need to update the system sending the inbound webhook to the new address if you wish to trigger the duplicated flow.

1. Navigate to Integrations > Setup connection > API token.
   
2. You will be prompted to provide a helpful Name and Description. Then, click Generate.
   
3. Once generated, the API token is shown in two different formats (HTTP header or basic authentication) and either can be used to secure inbound payloads to Pendula.

   Make sure to store the generated API token securely, as this cannot be shown again.

   
4. Ensure the credentials are saved securely, check the I have saved these credentials securely checkbox, and select Done. Now you can use this API Token to authenticate inbound payloads to the webhook trigger in the Flow builder.

Editing API tokens

You can edit Name and Description of an API token. Click on settings, make the changes and click on Update connection.

Deactivating API tokens

You can deactivate API tokens that are no longer used, or for which access is no longer authorised, at any time. Once deactivated, services using this API token will no longer be authenticated. 

1. In Integrations, under Connections, locate the 'Active' API token you wish to deactivate.
2. Under the Actions column, select Deactivate API token. Follow the prompts to continue.
   

   Note that API tokens can take up to 60 seconds to be deactivated.

Reactivating API tokens

You can reactivate API tokens that have previously been deactivated (represented by the 'Inactive' status) in order to authenticate services using the API token.

1. In the Integrations page, locate the 'Inactive' API token you wish to reactivate.
2. Under the Actions column, select Reactivate API token.
   

   Note that API tokens can take up to 60 seconds to be reactivated.

Deleting an API token

You can permanently delete 'Inactive' API tokens. Note that this cannot be undone, and services using this API token will no longer be authenticated.

1. In the Integrations page, locate the API token you wish to delete. Note that an API token must be 'Inactive' to be deleted.
2. Under the Actions column, select Delete API token. Follow the prompts to continue.

Webhook trigger node

A webhook is a way for an application to automatically exchange real-time data with other applications. It functions as an HTTP request triggered by an event in a source application and sent to a destination application with a data payloadInsert definition here. However, the process of setting up webhooks can vary based on the capabilities of the third-party applications involved.

What are configuration methods?

Configuration methods refer to the different ways you can set up and manage the parameters required for integrating Webhooks with third-party applications. These parameters typically include the webhook URL (where the webhook data is sent), authentication details, and any custom headers needed for the requests. Webhook URL is a specific type of HTTP callout URL used for webhooks, where the URL is designated to receive automated HTTP requests triggered by specific events in the source system.

While many third party apps can trigger webhooks, how simple or complex this is will depend on the third party app itself. Below are different configuration methods, starting with the simplest:

Configuration within Third Party via Basic Auth

Using Basic Authentication is a secure way to ensure that only authorised systems can communicate with the webhook trigger. This configuration is ideal when the third party allows specifying both an HTTP Callout URL and Basic Authentication details (username and password).

• HTTP Callout URL

  This is the endpoint where the third party will send HTTP requests. Specify Pendula’s inbound webhook URL in the third party system’s settings.

• Basic Authentication

  Use a combination of a username (typically the tenant ID) and a password (Pendula’s Inbound API token) for authentication. These credentials should be included in every request to ensure secure communication.

Example configuration

Webhook URL: <https://api.pendula.com/webhook>
Username: tenant123
Password: api_token_abc123

To test the configuration, you can use a curl command to simulate a POST request with Basic Authentication:

curl -X POST <https://api.pendula.com/webhook> \\
     -u tenant123:api_token_abc123 \\
     -H "Content-Type: application/json" \\
     -d '{"event":"customer_update","data":{"id":"1234","status":"active"}}'

• X POST: Indicates that the request method is POST.
• u tenant123:api_token_abc123: Supplies the Basic Authentication credentials (username:password).
• H "Content-Type: application/json": Sets the request header to indicate that the body content is in JSON format.
• d '{"event":"customer_update","data":{"id":"1234","status":"active"}}': Provides the actual data being sent in the request body, formatted as JSON.

Other methods

Configuration within Third Party via Custom Headers

Use this if the third party allows specifying:

• HTTP Callout URL - This is where the Pendula’s Inbound webhook URL can be specified.
• Custom Header to be attached on every request. This is another way of specifying Pendula’s Inbound API token.

Example configuration

Webhook URL: <https://api.pendula.com/webhook>
Custom Header:
    Key: Authorization
    Value: Bearer api_token_abc123

curl -X POST <https://api.pendula.com/webhook> \\
     -H "Authorization: Bearer api_token_abc123" \\
     -H "Content-Type: application/json" \\
     -d '{"event":"customer_update","data":{"id":"1234","status":"active"}}'

Calling via a Simple HTTP Proxy Server

Use this if the third party:

• Does not allow specifying an http callout url
• Allows a HTTP proxy application to be running in their tech stack

To set this up, a proxy server must be configured to receive requests. The proxy server then forwards requests to Pendula.

Calling via a Simple Intermediary Application

Use this if the third party does not allow specifying an HTTP callout URL and requires integrations to follow an app approach.

To set this up, an intermediary app must to configured to receive and forward requests to Pendula. An intermediary app may process and modify the data before forwarding.

Configuration via Third Party Code

Use this if third party integrations are specifying using a code configuration approach. The code would send authenticated requests to Pendula.

Pendula can authenticate each HTTP request made with Make a web request using secure credentials. Having a credential with the request ensures the communication between Pendula and the external application is secure, and is required in some cases. Currently, Pendula supports securely storing: request headers, bearer token and username and password.

• Request Headers: Similar to instructions on a parcel, request headers define the handling and processing of data in a web request. These headers provide the server with details such as data format, handling procedures, and additional context for processing the request. Pendula securely records these specifications as key-value pairs, catering to a variety of operational requirements including content type, caching policies, and identification protocols.
• Bearer Token: This security token acts as a digital access card, granting entry to specific services after a successful authentication. It streamlines the validation process, allowing for a secure yet effortless way to repeatedly assert one's access rights without constant re-authentication. Pendula's storage solution securely retains these tokens, automating their inclusion in requests to services that mandate verified access.
• Username and Password: These traditional identifiers serve as a fundamental method of authentication. When a system necessitates such a verification method, Pendula's secure storage ensures these credentials are safely stored and accurately transmitted. This preserves the integrity and confidentiality of the user's access credentials.

Adding credentials to Pendula

In the Integrations page, go to Setup new connection and select Web request credentials.

Then, you will need to select the type of credentials you wish to store.

Adding a request header

Request headers are key-value pairs that are in the header of the HTTP request.

1. Give a unique, helpful name to the credentials.
2. Add an optional description to further describe what the credentials are used for (e.g. Sales CRM authentication).
3. Enter credentials key-value format.
4. Save credentials.

Adding a bearer token

A bearer token is a string that is passed in the Authorization header of the HTTP request.

1. Give a unique, helpful name to the credentials.
2. Add an optional description to further describe this integration.
3. Enter bearer token.
4. Save credentials.

Adding a username and password

Username and password that is passed in the Authorization header of the HTTP request.

1. Give a unique, helpful name to the credentials.
2. Add an optional description to further describe this integration.
3. Enter username and password.
4. Save credentials.

Adding saved credentials to web requests

After securely storing your credentials in Pendula, you can easily select them within the Make a Web Request node. This node allows you to execute HTTP requests as part of your automated workflows. By selecting saved credentials during the node configuration, Pendula ensures that each web request it makes on your behalf is authenticated, thus maintaining the security and integrity of data exchanges with external services.

For a detailed guide on configuring the make a web request node, see Make a web request Date Action

Updating credentials

1. Navigate to Integrations > My integrations
2. Under Action connections, select on the settings icons of the credential you want to update.
3. Update fields, Name and Description, as necessary.
4. Click on Update connection.

You cannot read credentials before updating them as they are stored securely and cannot be surfaced.

"kinesis:ListShards" 
"kinesis:GetShardIterator" 
"kinesis:GetRecords"
"kinesis:PutRecord"
"kinesis:PutRecords"

Once setup in the AWS Management Console is complete, you can head back into Pendula to add this integration.

What does the Amazon Kinesis Integration enable?

How to add the integration into Pendula

What does the Amazon Kinesis Integration enable?

Adding the Amazon Kinesis Integration into Pendula will enable the Amazon Kinesis trigger node to be used, and flow activity (aka 'Activity Sync') to be recorded and transmitted between Pendula and Amazon Kinesis. 

Activity sync

Activity sync, enabled by integrating Amazon Kinesis into Pendula, records important events of a triggered flow such as email or SMS content, message delivery and sent times. This data is then written into Amazon Kinesis, where it can also be read from there.

Below is the type file for the events passed across the Activity Sync:

/**
* Common types
*/
type Address = string;
type MessageId = string;
type ExperienceId = string;
type Instant = string;

type EmailPayload = {
    kind: "email"
    sender: Address;
    recipient: Address;
    subject: string;
    body: string;
    replyTo?: string;
}

type SmsPayload = {
    kind: "sms"
    sender: Address;
    recipient: Address;
    body: string;
}

type MessagePayload = EmailPayload | SmsPayload;

type ActivitySyncError = {
    errorMessage: string
    errorCode?: string
}

type ExperienceContext = {
    experienceId: string
}

type FlowContext = {
    flowId: string
    flowName: string
    flowVersion?: number
}

type NodeContext = {
    nodename: string
}

type WorkflowContext = {
    experienceContext: ExperienceContext
    flowContext: FlowContext
    nodeContext?: NodeContext
}

type CustomContext = {
    [key: string]: any
}

/**
* Integration Inbound types
*/
type KinesisTriggerRecord = {
    payload: any
    customContext: CustomContext
}

/**
* Integration Outbound types
*/
    type OnMessageQueued = {
    kind: 'queued'
    messageId: MessageId
    payload: MessagePayload
    timestamp: Instant
    workflowContext?: WorkflowContext
    customContext: CustomContext
}

type OnMessageValidationFailed = {
    kind: 'validation-failed'
    messageId: MessageId
    errors: ActivitySyncError[]
    timestamp: Instant
    workflowContext?: WorkflowContext
    customContext: CustomContext
}

type OnMessageSentToGateway = {
    kind: "sent-to-gateway"
    messageId: MessageId
    timestamp: Instant
    workflowContext?: WorkflowContext,
    customContext: CustomContext
}

type OnMessageRejectedByGateway = {
    kind: "rejected-by-gateway"
    messageId: MessageId
    errors: ActivitySyncError[]
    timestamp: Instant
    workflowContext?: WorkflowContext,
    customContext: CustomContext,
}

type OnMessageDelivered = {
    kind: "delivered"
    messageId: MessageId
    timestamp: Instant
    workflowContext?: WorkflowContext,
    customContext: CustomContext,
}

type OnMessageBounced = {
    kind: "bounced"
    messageId: MessageId
    errors: ActivitySyncError[]
    timestamp: Instant
    workflowContext?: WorkflowContext,
    customContext: CustomContext,
}

type OnMessageOpened = {
    kind: "opened"
    messageId: MessageId
    timestamp: Instant
    workflowContext?: WorkflowContext,
    customContext: CustomContext,
}

type OnInboundMatchedIntent = {
    kind: 'inbound-matched-intent'
    messageId: MessageId
    parentMessageId?: string
    matchedIntentKey: string
    timestamp: Instant
    workflowContext?: WorkflowContext,
    customContext: CustomContext,
}

type OnInboundUnmatched = {
    kind: 'inbound-unmatched'
    messageId: MessageId
    payload: MessagePayload
    timestamp: Instant
    workflowContext?: WorkflowContext,
    customContext: CustomContext,
}

type OnExperienceStart = {
    kind: 'experience-start'
    experienceId: ExperienceId
    timestamp: Instant
    workflowContext?: WorkflowContext,
    customContext: CustomContext
}

type OnExperienceFinish = {
    kind: 'experience-finish'
    experienceId: ExperienceId
    timestamp: Instant
    outcome: any
    workflowContext?: WorkflowContext,
    customContext: CustomContext
}

type OnExperienceFailed = {
    kind: 'experience-failed'
    experienceId: ExperienceId
    timestamp: Instant
    workflowContext?: WorkflowContext,
    customContext: CustomContext
    errorDetails: ActivitySyncError[]
}

Amazon Kinesis Trigger Node

This node allows you to initiate a flow via the Kinesis stream. It transmits data (aka 'payload') from the Amazon Kinesis data stream into your flow.

Learn more about using the Amazon Kinesis Trigger Node in Pendula here

Below is the type file for the Kinesis Trigger record:

import { CustomContext } from "../context"
​
type KinesisTriggerRecord = {
payload: any
customContext: CustomContext
}

How to add the integration into Pendula

Follow the steps below to add Amazon Kinesis into Pendula:

1. Login to your Pendula tenant.

2. Navigate to Integrations screen.

3. Select Amazon Kinesis integration under the Add New section.

4. Input a unique API Name (required) and description (optional).

5. Input your AWS Access Key ID and AWS Secret Access Key of your data stream from your AWS Management Console. 

6. Click Save Integration. You can now use the Amazon Kinesis trigger node in your flows.

Learn more about using merge fields here.

Promotions engines like Talon.One can be used to validate and track coupon usage, providing a clear record of interactions during your customer journey.

Integrating Talon.One with Pendula gives you the ability to create or retrieve personalised coupons that target your customers preferences and behaviours at the optimal time in the customer journey, allowing you to maximise engagement and drive results.

Coupon codes are created by using the web request node to make a GET request to Talon.One.

Pre-requisites

To create the coupon, you’ll need to know

• the number - applicationId - of the Talon.One application you are using
• the number - campaignId - of the Talon.One campaign within the application
• the value - externalCampaignId - you use to identify the Talon.One campaign in your system of record

Refer to the Talon.One documentation for more information about where to find these in your Talon.One instance.

Add flexibility with an identifier

These the basic attributes that are required to generate a coupon code, and you could start with these, but let’s add an optional parameter - identifier - so we can decide if we want the GET request to either create a new coupon code, or to retrieve an existing coupon code.

When an identifier value is provided as part of the request, Talon.One will check to see if that value already exists inside the Talon.One database.

• If the value in the identifier does not exist, Talon.One will create a new coupon code
• If the value in the identifier already exists, Talon.One will retrieve the existing coupon code that matches this identifer

This way, you can use the same node configuration in different parts of the flow, or in separate flows, to create a new coupon for a new customer, or to retrieve an existing coupon code when you need to validate or redeem the coupon.

The value for identifier can be anything within your system of record that uniquely identifies an individual customer.

Now that you have all the information you require, let's see how to use this in a Pendula flow.

To create or retrieve coupons from Talon.One:

1. Drag the Web Request node into your flow at the point where you want to create or retrieve a coupon code.
2. Set the Request type to GET.
3. Copy and paste the following into the API endpoint URL field:
   https://integration.talon.one/customer_engagement/coupon?applicationId=<VALUE>&campaignId=<VALUE>&externalCampaignId=<VALUE>&identifier=<VALUE>
   Replace each <VALUE> with the matching values from your systems.
   These values can either be added manually, or dynamically through merge fields.
4. Select Headers from the Authentication drop down.
5. Select the credential you have configured for Talon.One.
6. In the Request headers section, click Add a header.
7. Paste the following into the Header field:
   customer-engagement-platform-name
8. Enter pendula as the Value for this field.
9. Click Add a header and paste destination-hostname into the Header field.
10. In the Value field, enter the base URL for your Talon.One instance (e.g. - mycompany.europe-west1.talon.one).
11. Click Add a header and paste X-DRY-RUN into the Header field, and false into the Value field.
12. Click Save to save your changes and close the node editor.

Using within a flow

A GET request to Talon.One can be used at any point in a flow where coupon codes are part of the customer journey. For example, the screenshot of the flow at the start of this article creates a coupon code to send to a customer as a thank you on their birthday each year.

Because Pendula can create or retrieve coupon codes at any time, you can also use this method for self-serve flows, like letting a customer check their loyalty points value by SMS, or inviting them to enter a competition by scanning a QR code with a special word, as shown in the following example.

Webhooks can be used in Talon.One applications to send promotions to your customers through Pendula's messaging channels.

As Talon.One webhooks are available to any application, you can create them once and then use them in as many campaigns as you want, in any linked application.

For example, if you would like to send coupons to customers via SMS, you can create one Talon.One webhook and one Pendula SMS flow, and then use these any time you want to send coupons via SMS as part of a campaign.

There are two steps to enable this in your Talon.One instance:

1. Create a Talon.One webhook and link it to your Pendula flow
2. Select the webhook as an Effect in a campaign rule

Let's step through the process.

Creating a Talon.One webhook to Pendula

In your Talon.One tenant:

1. Navigate to Account > Tools > Webhooks and click Create Webhook.
2. Enter a Webhook title that describes the Pendula flow you are sending to.
3. Select the Applications you want to use the webhook in (note that you can update this list at any time).
4. Add a parameter with the Param name of api
5. Enter a Param description for the api key.
6. Select POST as the Request Verb, and paste the URL of your Pendula webhook into the URL field.
7. Paste the text Authorization: ${$api} into the first Header field.
   
   
   
   
   
8. In the Request payload field, paste the JSON for the Talon.One attributes you want to send to Pendula. These will depend on your available data. An example payload for some data that is useful for Pendula flows is shown below.

   {
   "name": "${$Profile.Attributes.Name}",
   "email": "${$Profile.Attributes.Email}",
   "phone": "${$Profile.Attributes.Phone}",
   "customerID": "${$Profile.IntegrationId}"
   }

9. Click Save.

You can now select the webhook as a Rule Effect in any of the applications you have linked.

Selecting the webhook as a Rule Effect

Now that you've created a webhook and linked it to a Pendula flow, you can enable this as an Effect in any Campaign Rule, for any active Campaign that is part of the linked applications.

After selecting a webhook, paste the API key for your Pendula tenant into the provided field, using the format Basic <key>, then click Done to apply the key.

The webhook is active as soon as you Save your changes, so you can quickly start sending promotions to your customers through Pendula.

• A Segment Business plan, with Engage Foundations
• A Pendula API Token 
• A Segment source, with incoming events. 

To Trigger Pendula from a Segment Audience

1. Create a destination - a specific Pendula flow destination for the relevant campaign.
   • See Pendula documentation here for creating destinations.
2. Build an audience within Segment Engage - Refer to the Segment Documentation on Engage audiences.
   • When creating the audience, ensure to tick ‘Include Historical Data’ to include existing audience members. If not ticked, only new audience members will be added to the audience.
     
     
3. Once the audience has been created, connect the audience to the Pendula destination.
   • Connection settings - Send identify (Can use default setup, or configure custom setup)
     
     
4. After creation, Segment will send each historical audience member onto the destination - in this case, a Pendula flow. It will also continue to send audience members who meet the criteria after the audience creation.
   • It might take some time for audience members to begin being sent to the destination, depending on the size of the audience.

Keep in mind that once an audience has been created, all new profiles that match the conditions will be added to the audience (and trigger a Pendula flow).

If you're running a one time campaign, disable the audience or remove the destination from the audience after the campaign ends to stop flows being triggered for new audience members.

1. Select the Integrations tab.
2. In the Setup connection section, click Username & Password.
3. Enter the Name that will be visible when selecting a Connection in a WhatsApp node.
4. Enter a Description that description that will be visible in the list of integrations.
5. Paste your WhatsApp Account ID into the Username field.
6. Paste your WhatsApp Account Bearer Token into the Password field.
   
   
   
   
7. Click Save connection.

The connection for your WhatsApp Business Account is now visible in the list of integrations, and can be selected from a WhatsApp node.