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. We will add the custom authorization header to the HTTP headers. The custom authorization header allows you to verify that the call was made by our service and not some unauthorized 3rd party.

Your server will then need to answer with a message that we will then forward to the user.

Example HTTP body & server response

The HTTP body we send with every HTTP API call includes the last two comments, details on the current session (userId, name, email, ...) and conversation (ticketId, custom data, ... ).

{
	"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.

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