How to
Make use of custom context

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"
}