Cloud Functions

In addition to integrating with Medchat via Webhooks and our in-house developed custom scripts, customers can now invoke endpoints that they own, develop, and manage independently via the Cloud Functions feature.

Note that Cloud Function endpoints you create will need to adhere to a contract published by Medchat, which includes a pre-defined payload of chat/chatbot context information and a string response payload to allow branching in Automation Studio.

📘

Endpoint Authentication

To authenticate the customer endpoints, please visit our page on Registered API.

📘

Feature Enablement

Cloud Functions is a Medchat premium feature. Please reach out to [email protected] to request enablement of this capability.

---

Create a Cloud Function

1. Navigate to Admin > Developer > Cloud Functions
2. Click on 'New Cloud Function' at the top right-corner of the page.
3. Fill in the following information:
   1. Cloud Function Name: name your cloud function/endpoint
   2. Details
      1. Registered API: choose from a list of configured Registered APIs to authenticate your endpoint. Please visit here for more information about Registered APIs.
      2. Endpoint URL (relative): provide the Endpoint URL relative to your Registered API
      3. Branch Options: add string response payload(s) that can be used for branching in a Chatbot

4. Click 'Create Cloud Functions' on the top-right corner of the panel to save.

---

Use Cloud Functions in Chatbots

To call a cloud function with Chatbots, search for the 'Execute Cloud Function' block in the Chatbot editor and add to your flow.

1. Navigate to Admin > Automation Studio, then click on a chatbot where you want to call a cloud function.
2. On the chatbot editor, add a new step in your flow and search for 'Execute Cloud Function' from the available list of chatbot blocks.
3. Select a your desired Cloud Function from the dropdown list.
   1. Save value to attribute: Select or add a new attribute that will store the returned string response from the Cloud Function
   2. Enable 'Add Failure Branch' to handle paths where the cloud function encounters an exception when attempting to return a response.

---

Trigger Cloud Functions based on Events

To call a cloud function using Triggers, navigate to Admin > Developer > Triggers. Click on 'New Trigger' at the top-right corner of the page to start configuration.

1. Add a Trigger Name, then click 'Create Trigger'
2. Details:
   1. Trigger name: Provide a name for your cloud trigger
   2. Select Action Type: Select 'Cloud Function'
   3. Select Cloud Function: select the specific cloud function to invoke when trigger events occur
3. Trigger Events: similar to Webhook Events, add events (such as Chat Status 'Chat Opened' or 'Chat Archived') that will trigger the cloud function.

---

Cloud Function API Contract

Customer endpoints need to adhere to the Medchat Cloud Function contract below:

Chatbot Execution:

When a cloud function is executed from a chatbot 'Execute Cloud Function' step, context about the chatbot step execution will be posted to the customer's cloud function endpoint:

Request: POST

{
  "type" : "CloudFunctionStepExecution",  // Allow for a type in case the same endpoint also handles webhook/trigger events.
  "orgId" : guid,
  "chatId" : guid,  // Represents either a LiveChat or an SmsChat depending on the ChatBotType.
  "executionId" : guid,
  "chatBotId" : guid,
  "chatBotName" : string,
  "chatBotType" : string,  // ["LiveChat", "SmsChat", "Journey"]
  "stepName" : string,    //
  "stepId" : string,    
  "timestamp" : datetime  // name exists for compatibility with Events.
}

Response:

The expected HTTP status code can be any successful code (200 - 299). All other status codes will be treated as an error and logged.

A response payload may have the following:

{
  "returnValue" : ""        // Can be used for branching on the chatbot.
}

📘

Note that if there is no response, or if the returned string value does not exist in the cloud function enumeration, then branching will follow the default path.

Trigger Execution

When a cloud function is executed from a Trigger, the event defined for the trigger will be passed to the cloud function. No payload is expected in the response. However, if a payload is received, it will get logged in the Trigger Executions view.