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.

Response

Gleap allows three types of responses, that can be combined (message, tags, attributes & startWorkflow).

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.

Tags

By passing back tags, you can set tags to the current conversation / ticket. This allows you to do further branching down the line.

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).