Custom API action

The custom API action allows you to to seamlessly connect your live external data with Gleap. This real-time data can be used to empower bot flows, enabling your customers to self-serve their inquiries automatically within the Gleap widget.

To use custom API actions, start by identifying common inquiries that your team spends a lot of time answering, particularly those without information available in Gleap. These may include questions about external systems, such as "What's my order status?" or actions like "Reschedule delivery."

Getting started

The first step to get started with our custom API actions is by defining an API url and optionally an authorization header.

The API URL is the URL that is being called when the custom API action gets triggered. You can insert variable into the URL as well as custom headers for authentication.

Request body

Gleap allows for two options - “Send all available data” and “Custom request body”.

Custom request body

The custom request body allows you to specify the exact body that the API call sends to your endpoint. Use variables to populate data into your request body template.

Send all available data

When using the “Send all available data” we send the following information to your endpoint:

{
	"conversation": {
		"id": "ID",
		"type": "INQUIRY",
		"project": "PROJECT_ID",
		"organisation": "ORGA_ID",
		"shareToken": "SHARE_TOKEN",
		"customData": {
			"somecustomkey": "customdataforticket"
		}
	},
	"session": {
		"id": "ID",
		"gleapId": "GLEAP_ID",
		"userId": "user123",
		"email": "sam@example.com",
		"name": "Sam",
		"value": 100,
		"customData": {
			"somecustomkey": "customdataforsession"
		}
	},
	"comments": [{}]
}

Our service require you to response with a HTTP 200 status as well as the following JSON content.

The message parameter can be a simple string, markdown string or complex TipTap JSON.

Response

Gleap allows four types of responses, that can be combined (message, tags, attributes & startWorkflow). Every response MUST be a JSON object like the example below. If you don’t want to perform any action, you can also send an empty JSON object.

A full example looks like this:

{
    "message": "This is an example message",
    "tags": ["Example", "Fancy"],
    "startWorkflow": "WORKFLOW_ID",
    "attributes": [{
        "type": "session",
        "path": "name",
        "value": "Max Smith"
    }, {
        "type": "ticket",
        "path": "customData.someAttribute",
        "value": "Demo data"
    }]
}

Messages

Message can either be a plain text, markdown OR tiptap json object. See examples below for more information.

Simple message example

{
	"message": "This is a response from the server and will be sent to the customer :)"
}

MarkDown examples

{
	"message": "This is a *response* from the server. [Read more](https://www.yourdomain.com)"
}

TipTap examples

Simple message:

{
    "message": {
        "type": "doc",
        "content": [
            {
                "type": "paragraph",
                "content": [
                    {
                        "type": "text",
                        "text": "This is a response from the server and will be sent to the customer :)"
                    }
                ]
            }
        ]
    }
}

Message with link:

{
    "message": {
        "type": "doc",
        "content": [
            {
                "type": "paragraph",
                "content": [
                    {
                        "type": "text",
                        "text": "This is a "
                    },
                    {
                        "type": "text",
                        "text": "response",
                        "marks": [
                            {
                                "type": "link",
                                "attrs": {
                                    "href": "https://example.com",
                                    "target": "_blank",
                                    "rel": "noopener noreferrer"
                                }
                            }
                        ]
                    },
                    {
                        "type": "text",
                        "text": " from the server and will be sent to the customer :)"
                    }
                ]
            }
        ]
    }
}

You can find out more on the markdown options here:

https://tiptap.dev/guide/output#not-an-option-markdown

Workflows

By passing back a workflow ID, Gleap will continue with the workflow you pass back. This is great for allowing your server to dynamically start other workflows.

The workflow ID can be found by opening the workflow, then clicking on “Edit trigger” → “Start workflow automatically” → then locate the workflow ID.

Attributes

You can also send back attributes, that Gleap will either assign to the ticket OR current contact. An example looks like this:

{
    "attributes": [{
        "type": "session",
        "path": "name",
        "value": "Max Smith"
    }, {
        "type": "ticket",
        "path": "customData.someAttribute",
        "value": "Demo data"
    }]
}

You will have to send each attribute individually in an array of attributes. Each attribute can have a type (session or ticket), path (the path to set the data on) and value (the actual value).

Help center