Concept: Activity

What is Activity Sync?

Activity Sync is a feature that emits real-time events as activity occurring during a flow. These events include:

• Message delivery: Notifications when messages are queued, sent, or delivered.

• Experience progress: Updates when an experience starts, completes, or encounters an issue.

• Node-specific actions: Details about actions like web requests or criteria evaluations.

External systems can subscribe to Activity Sync to:

• Monitor in real-time: Capture live activity data and act immediately on key events.

• Generate reports: Build detailed performance and engagement reports based on activity events.

• Automate responses: Trigger external workflows or processes in response to specific activity events.

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, End point configured)

Here is a successful, ‘Complete’ experience-finish activity. This particular example shows an experience that reached a configured End point named converted.

When an experience finishes at a named End point, the value field is populated with the configured End point value:

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

For more on how End points work and how values are used in flow reporting, see Flow performance reporting with End points.

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

Pendula always returns a 404 Not Found response when a request is made to a Webhook Trigger endpoint without valid credentials. This behaviour is intentional and designed to enhance security—preventing unauthorised users from discovering or probing endpoint URLs based on response codes.

Even if authentication details are missing or incorrect, the system will not return an authentication-specific error (such as 401 Unauthorized). Instead, it will always respond with a 404 to prevent endpoint enumeration.

If you're troubleshooting a webhook request failure, ensure that your credentials are correctly configured and that the external system sending the request includes the expected authentication details.

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. Pendula generates an API token that can be used as:

   • An Authorization Header: Preformatted as Authorization: Basic <token>.
   • Credentials for Basic Authentication: Split into a username (Tenant ID) and password (API token).
   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.

Activity sync provides a range of information about the performance of messages as they pass through your Pendula tenant. This information can be used in external systems for analytics and reporting, by connecting to the activity sync stream.

This article shows how to connect an activity sync stream from your Pendula tenant to Amazon Kinesis, and how to store that stream in an S3 bucket.

Prerequisites:

• Requires Administrator login to your AWS environment
• The Amazon Kinesis package must be enabled for your Pendula tenant

How to connect activity sync to Amazon Kinesis and S3

1. Log into your AWS Account.

2. As an Administrator, open the Management Console.

3. Search for “Kinesis” and select “Kinesis - Work with Real-Time Streaming Data”.

4. Click Create data stream.

5. Enter a Data stream name. NOTE: The Data stream name is used as the streamName when deploying a Pendula Activity Sync resource, later in this procedure.

6. Click Create data stream.

7. Copy the ARN value, so you can reference it in your policy.

8. Search for “IAM” and select “IAM - Manage access to AWS resources”.

9. In the IAM management screen, click Policies.

10. Click Create policy.

11. In the Policy editor, click the JSON button.

12. Paste the following JSON:

    {
    	"Version": "2012-10-17",
    	"Statement": [
    		{
    			"Sid": "PendulaAccess",
    			"Effect": "Allow",
    			"Action": [
    				"kinesis:GetRecords",
    				"kinesis:GetShardIterator",
    				"kinesis:ListShards",
    				"kinesis:PutRecord",
    				"kinesis:PutRecords"
    			],
    			"Resource": "Paste ARN Here"
    		}
    	]
    }
    

13. Paste the ARN for your stream into the Resource field.

14. Click Next.

15. Enter a Policy name and optionally, a Description, then click Create Policy.

16. In the IAM management screen, click Users.

17. Click Create user.

18. Enter a User name, then click Next.

19. Select Attach policies directly, and select the policy you just created.

20. Click Next.

21. Click Create user.

22. Select the user you just created.

23. Click Create access key.

24. Select Third-party service.

25. Select the Confirmation check box.

26. Click Next.

27. Click Create access key.

28. Select Third-party service as the Use case.
29. Click Next.
30. Enter a Description.
31. Click Create access key.

32. Copy and save the Access Key ID and Secret Access Key in a secure place. These credentials will be used when setting up your connection in Pendula.

33. Click Done.

34. Search for and select “S3” to create an S3 bucket.

35. Click Create bucket.

36. Enter a Bucket name and adjust settings as required for your environment, then click Create bucket.

37. Search for “Firehose” and select “Amazon Data Firehose”.

38. Click Create Firehose stream.

39. Select Amazon Kinesis Data Streams as the Source, and Amazon S3 as the Destination. Additional fields will appear after you select these.

40. In the Source settings Kinesis data stream field, select the Kinesis stream you created in step 4.

41. In the Destination settings S3 bucket field, select the bucket you created in step 32.

42. Adjust the remaining settings as required for your environment, then click Create Firehose stream.

Your Kinesis stream is now configured.

You can now set up your Amazon Kinesis connection inside your Pendula tenant.

How to connect your Pendula tenant activity sync to AWS Kinesis

After configuring your AWS Kinesis stream and S3 bucket, you can connect your Pendula tenant.

1. Log into your Pendula tenant.
2. Select the Integrations page.
3. In the Setup connection section, click Amazon Kinesis.
4. Enter a Name for the connection.
5. Enter a Description for the connection to make it easy to identify.
6. Paste your AWS Access Key ID and AWS Secret Access Key into the fields.
7. Click Save connection.

To start data streaming from Pendula, contact your Pendula representative with the name of your Kinesis data stream and the API name from your tenant connection, so they can enable the stream for your environment.

Learn more about using merge fields here.

HubSpot private apps are a powerful tool to quickly connect with external services, like Pendula, that support webhooks. Creating a private app takes about 15 minutes, and can be done by any user with the "Super Admin" role.

Step 1 - Name your private app

1. Log in as a Super Admin and navigate to Settings > Integrations > Private Apps.
2. Click Create a private app.
3. In the Basic Info tab, enter a Name, and, optionally, a Logo and Description that will help you to identify the app within your HubSpot environment.

Step 2 - Select the data you want to use with Pendula

Select the Scopes tab and select the HubSpot data you want to use in your Pendula flows.



Use the search field to find the data you want to use, then select the correct permissions - either Read or Write, for the selected data.

For this example, our private app uses the following scopes:

• crm.objects.contacts.read
• crm.objects.contacts.sensitive.read
• crm.objects.contacts.sensitive.write
• tickets
• tickets.sensitive

Activating your private app

To active your private app, click Create app.

This generates a modal that reminds you to securely store the token that will be displayed on the next screen.

Click Continue creating.

Copy the token and securely save it so you can access it later. This is the token you will use to authenticate your webhooks from Pendula.

Once you have saved the token, click Close. Your private app is now ready to be used with Pendula.

NOTE: You only need to create one private app to connect to Pendula. Once it is set up, the private app can be used for any flows where you want to read or write data from HubSpot. You can update the Scopes at any time to add or remove permissions as required.

Saving your HubSpot token in Pendula

HubSpot private apps use a bearer token for authentication. You can securely store this in Pendula and use it in any of your HubSpot flows.

To store the token in Pendula:

1. Navigate to Integrations.
2. Under the Setup connection heading, select Web request credentials.
3. Select Save a bearer token.
4. Enter a Name and Description that will make it easy to identify the credentials.
5. Copy and paste the HubSpot token into the Token field.
6. Click Save connection.

The HubSpot credentials for your private app are now available to be used in any Pendula flow.

Creating your Pendula flow

This flow uses Pendula's ability to read and write via webhooks to

• capture the customer request via QR code or text input
• request an identifier for the contact - in this case, the customers email address
• verify that the contact exists
• retrieve the first name from the contact record
• request more information from the customer, using their first name
• create a ticket in HubSpot linked to their contact record
• let the customer know that a ticket has been created and that someone will be in contact soon.

This flow uses the Inbound message trigger to start the flow.

Enter the keywords from your QR code into the Value field, and set the Rule to is exactly to match messages that exactly match those keywords.

The Conversation node is used to acknowledge the request, and identify the customer.

Use a free reply path to capture the email address.

Now that the customer has responded with their email address, we can check that against our HubSpot record to verify that the Contact exists, and return any information we need from the Contact record to continue the conversation.

Add the Make a web request node to the flow and select Bearer from the Authentication field, and the HubSpot credentials you saved earlier.

You can now use the messageBody merge field to include the email address that the customer supplied in the GET request to HubSpot.

Copy and paste this URL into the API endpoint URL field:

https://api.hubapi.com/crm/v3/objects/contacts/messageBody?idProperty=email

Replace the messageBody part of the URL with the messageBody field from the merge field explorer values for your flow.

This request will validate that a contact record exists that matches the email record, and return any details about that contact - for example, their first name - that we want to use in the rest of the conversation.

Paste the following sample payload in the Merge fields > Payload tab of the Conversation node so you can reference this information in following nodes.

{
"id": "51",
"properties": {
"createdate": "2023-12-18T01:08:50.238Z",
"email": "bh@hubspot.com",
"firstname": "Brian",
"hs_object_id": "51",
"lastmodifieddate": "2023-12-18T01:08:54.780Z",
"lastname": "Halligan (Sample Contact)"
},
"createdAt": "2023-12-18T01:08:50.238Z",
"updatedAt": "2023-12-18T01:08:54.780Z",
"archived": false
}

Next, we'll use another Conversation node to ask the customer about the nature of their inquiry.

From the merge field explorer, select the merge field(s) you want to use in the conversation.

Use a free reply path to capture the customers response.

Now that we have the information needed to create a ticket, we can create the HubSpot ticket.

Add the Make a web request node to the flow and select Bearer from the Authentication field, and the HubSpot credentials you saved earlier.

Select POST as the Request type. Copy and paste this URL into the API endpoint URL field:

https://api.hubapi.com/crm/v3/objects/tickets

In the Request body section, select the Convert to code option from the more menu.

Copy and paste the following code into the JSON field:

{
"properties": {
"hs_pipeline": "0",
"hs_pipeline_stage": "1",
"hs_ticket_priority": "HIGH",
"subject": "{{ conversation_2.messageBody }}"
},
"associations": [
{
"to": {
"id": "{{ webRequest_1.id }}"
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 16
} ]
}
]
}

Replace the {{ conversation_2.messageBody }} and {{ webRequest_1.id }} with the merge field explorer values for your flow.

Paste the following sample payload in the Merge fields > Payload tab so you can reference the ticket  information in SMS reply.

{
"id": "2807216478",
"properties": {
"createdate": "2024-06-07T04:23:59.750Z",
"hs_helpdesk_sort_timestamp": "2024-06-07T04:23:59.750Z",
"hs_last_message_from_visitor": "false",
"hs_lastmodifieddate": "2024-06-07T04:23:59.750Z",
"hs_object_id": "2807216478",
"hs_object_source": "INTEGRATION",
"hs_object_source_id": "3405549",
"hs_object_source_label": "INTEGRATION",
"hs_pipeline": "0",
"hs_pipeline_stage": "1",
"hs_ticket_id": "2807216478",
"hs_ticket_priority": "HIGH",
"subject": "sample ticket"
},
"createdAt": "2024-06-07T04:23:59.750Z",
"updatedAt": "2024-06-07T04:23:59.750Z",
"archived": false
}

Now that the ticket is created and linked to the contact, we'll use the Outbound SMS node to let the customer know.

Copy the detail(s) of the ticket that you want to use in your reply from the merge field explorer.

Your flow is now ready to activate and to start receiving customer inquiries!

Microsoft Fabric is a unified data platform that streamlines data processing, storage, and analytics in a single, cohesive environment. By sending your data to Microsoft Fabric, you can unlock advanced capabilities that can help you gain deeper insights into customer behaviour and engagement trends.

A standout feature within Microsoft Fabric is Power BI. This powerful business intelligence tool lets you create interactive, visually compelling dashboards and reports, making it easier to identify key performance indicators, track trends, and make data-driven decisions that enhance customer engagement and drive business growth.

This article shows how to route activity sync data from your Pendula tenant to Microsoft Fabric, by connecting to our Amazon Kinesis data stream.

Prerequisites

• requires an active Pendula activity sync connection to Amazon Kinesis
• requires your Kinesis Access Key ID and Secret access key

How to connect Microsoft Fabric to your Pendula Kinesis data stream

1. Log into your Microsoft Fabric account.
2. In the left menu, select Real-Time.
3. Click Connect data source.
4. Search for Kinesis.
5. Click Connect on the Amazon Kinesis Data Streams tile.
6. Click New connection.
7. Enter the Name of your Kinesis data stream.
8. Enter your Amazon Kinesis Access key ID.
9. Enter your Amazon Kinesis Secret access key.
10. Click Connect.
11. Select the AWS region your Kinesis data stream is located in.
12. Click Next.
13. Review your settings and adjust if necessary, then click Connect.
14. When Fabric has successfully established the connection, click Finish.

Your connection to the Pendula Kinesis data stream is now available to use in your Microsoft Fabric environment.

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.