Custom Actions API

The Custom Actions API allows you to define custom actions that can be triggered by users when they chat with your AI.

​

Examples

Examples of custom actions include:

• Sending an email to the user with a discount code when they request one.
• Sending a message to a Slack channel when the user requests a callback.
• Providing product recommendations from your own database or inventory system.
• Collecting feedback from users and storing it in your own database.
• Collecting leads and storing them in your CRM system.

​

How it works

1. You need to define a custom action in the molin.ai dashboard. You can define the name, description, and parameters that the action requires (e.g. email address, phone number, etc).
2. Your team needs to implement an API endpoint. This endpoint should accept the parameters defined in the dashboard and perform the action (e.g. generate a coupon and email it to the user).
3. You should enable the action from the dashboard and test it in the chat preview.

​

How to create a custom action

1. Go to the AI Actions page and click on the New Custom Action button.
2. Fill in a name and description. The name should describe succinctly what the action does. The description should provide more details about the action. Both the name and the description will be given to our AI so that it knows when to call the action. See the example screenshot below
3. Define the parameters that the action requires. For example, if the action is to email the user a coupon, you might need the user’s email address. You must define correctly the type of each parameter (e.g. string, number, or boolean).
4. Define the endpoint URL where the action will be triggered. This URL should be accessible from the internet via a POST request and should accept the parameters defined in the previous step. The endpoint should return plain text or JSON.

​

How to create your endpoint

You can use any stack to create an HTTP web server that conforms to the following requirements.

​

Requirements

​

Request

The request will be a POST request with a JSON body. The body will contain the parameters defined in the dashboard. You can read the x-molin- headers to get additional information about the widget and conversation.

POST https://your-endpoint.com/your-action
Content-Type: application/json
x-molin-custom-actions-version: 2024-11-01
x-molin-widget-id: widget-id
x-molin-conversation-id: conversation-id

{
  "your_defined_param": "some value from user input"
}

​

Response

The response should be plain text or JSON. The entire body will be given to the AI so it can respond to the user.

Content-Type: text/plain or application/json

any plain text or JSON

​

Example

POST https://molin.your-shop.com/actions/generate-coupon-code
Content-Type: application/json
x-molin-custom-actions-version: 2024-11-01
x-molin-widget-id: widget123
x-molin-conversation-id: fce602af-39f2-4717-b2e0-698357b4f109

{
  "email": "john@testington.com"
}

Content-Type: text/plain

Success. Generated coupon code: LUCKY53215

​

Using a test endpoint for development

If you wish to test quickly, you can use Beeceptor, a free service that allows you to create a temporary endpoint that you can use to test your custom action.

You can use the following URL as your endpoint in your custom action:

https://custom-action-generate-coupon-code.free.beeceptor.com

You can view requests sent to it here.