Receive chatbot messages

23 February 2026 02:07

The chatbot sends events, messages, and handover requests to the URL specified in your webhook integration. You must acknowledge each message request either via a delivery acknowledgement or an echo message before the chatbot will send the next message. Typing activity and handover events do not need to be acknowledged.

All requests follow the basic request payload and include additional properties specific to that event, message, or handover request:

Typing indicator event
Handover request to hand the chatbot user over to a livechat agent.
Messages:

Messages may also include Quick Replies in the payload.

Conversation ID

Each webhook chat has a unique identifier so you can maintain multiple chats from the same integration or pick up where a previous chat left off. For compatibility with other platforms such as Sunshine Conversations, this identifier is called the conversation ID. When working with the webhook API, the conversation ID identifies a specific chat between your chatbot and the webhook integration, not a conversation in the inGenious AI platform.

Request payload

Property	Description
app.teamId	The chatbot's team ID, available in general settings.
app.botId	The chatbot ID, available in general settings.
webhook.id	The id for this webhook integration, available in the webhook integration page.
webhook.version	The version of the webhook request payload sent in the request. The current version is v1.
events	An array of event objects. Each object in the array contains: A unique identifier for the event. The UTC timestamp the event was sent. The type of event as a string: "conversation:typing" for typing activity events. "conversation:message" for messages. "conversation:handover" for handover events. The event payload object, which contains: The id identifying the chat, called the conversation ID. This is not related to the conversations in your inGenious AI chatbot. Additional properties specific to the event type.

{ 
  "app": { 
     "teamId": "xxxxxxxx",
     "botId": "xxxxxxxxx"  
  }, 
  "webhook": { 
     "id": "xxxxxxxxxx",  
     "version": "v1" 
  }, 
  "events": [ 
     { 
       "id": "event_id", 
       "timestamp": 1458692752478, 
       "type": "{eventType}", 
       "payload": { 
          "conversation": { 
            "id": "{conversationId}" 
          }, 
          {eventSpecificPayload} 
        } 
     } 
  ] 
}

Typing indicator

The typing indicator event is sent when the chatbot starts or stops typing. You don't need to acknowledge a typing event.

Property

Description

payload.activity.type

The type of activity as a string. Activities include:

"typing:start"
"typing:stop"

payload.activity.author.type

The author of type "chatbot".

{ 
  "app": { 
     "teamId": "xxxxxxxx", 
     "botId": "xxxxxxxxx" 
  }, 
  "webhook": { 
     "id": "xxxxxxxxxx", 
     "version": "v1" 
  }, 
  "events": [ 
     { 
       "id": "event_id", 
       "timestamp": 1458692752478, 
       "type": "conversation:typing", 
       "payload": { 
          "conversation": { 
            "id": "{conversationId}" 
          }, 
          "activity":{
            "type":"typing:start",
            "author":{
              "type": "chatbot"
            }
          }
        } 
     } 
  ] 
}

Handover request

The chatbot sent a request to hand the chatbot user over to a livechat agent. You don't need to acknowledge a handover request. The chatbot will not process or respond to further messages from your webhook until you send a handback request.

Property	Description
payload.handover.metadata	An object containing any additional metadata for the handover.

{ 
  "app": { 
     "teamId": "xxxxxxxx", 
     "botId": "xxxxxxxxx" 
  }, 
  "webhook": { 
     "id": "xxxxxxxxxx", 
     "version": "v1" 
  }, 
  "events": [ 
     { 
       "id": "event_id", 
       "timestamp": 1458692752478, 
       "type": "conversation:handover", 
       "payload": { 
            "conversation": { 
          "id": "{conversationId}" 
          }, 
          "handover": {
             "metadata" : {}
          }
        } 
     } 
  ] 
}

Messages

All messages include a message property in the payload property. Include this message property in your delivery requestor message echo request to acknowledge the message.

Text message

The chatbot sent a text bubble. You must acknowledge this message.

Property	Description
payload.message.id	The unique identifier of the message.
payload.message.author.type	The author of type "chatbot".
payload.message.content.type	The content of type "text".
payload.message.content.text	The text of the message.
payload.message.content.replies	An array of Quick Replies, if included.
payload.message.metadata	Any additional metadata included with the message such as Tags.

{ 
  "app": { 
     "teamId": "xxxxxxxx", 
     "botId": "xxxxxxxxx" 
  }, 
  "webhook": { 
     "id": "xxxxxxxxxx", 
     "version": "v1" 
  }, 
  "events": [ 
     { 
       "id": "event_id", 
       "timestamp": 1458692752478, 
       "type": "conversation:message", 
       "payload": { 
            "conversation": { 
          "id": "{conversationId}" 
          }, 
          "message ":{
             "id":"xxxxxxxx",
             "author":{
                "type": "chatbot"
             },
             "content" : {
                "type":"text",
                "text":"I am a friendly chatbot!"
             },
             "metadata" : {}
          }
        } 
     } 
  ] 
}

Image message

The chatbot sent an image. You must acknowledge this message.

Property	Description
payload.message.id	The unique identifier of the message.
payload.message.author.type	The author of type "chatbot".
payload.message.content.type	The content of type "image".
payload.message.content.mediaUrl	The URL of the image.
payload.message.content.replies	An array of Quick Replies, if included.
payload.message.metadata	Any additional metadata included with the message such as Tags.

{ 
  "app": { 
     "teamId": "xxxxxxxx", 
     "botId": "xxxxxxxxx" 
  }, 
  "webhook": { 
     "id": "xxxxxxxxxx", 
     "version": "v1" 
  }, 
  "events": [ 
     { 
       "id": "event_id", 
       "timestamp": 1458692752478, 
       "type": "conversation:message", 
       "payload": { 
          "conversation": { 
            "id": "{conversationId}" 
          }, 
          "message ":{
             "id":"xxxxxxxx",
             "author":{
                "type": "chatbot"
             },
             "content" : {
                "type":"image",
                "mediaUrl":"https://media.au.ingenious.ai/exampleImage.jpg"
             },
             "metadata" : {}
          }
        } 
     } 
  ] 
}

Button message

The chatbot sent one or more buttons. You must acknowledge this message.

Property	Description
payload.message.id	The unique identifier of the message.
payload.message.author.type	The author of type "chatbot".
payload.message.content.type	The content of type "button".
payload.message.content.text	The text message included with the buttons.
payload.message.content.buttons	An array of button objects. Each object contains: "text" to display on the button "type" indicating what the button does: "link" to open a website, send an email, or make a phone call. "postback" to start a passage. "webview" to open a webview. Additional properties depending on the button type.
payload.message.content.replies	An array of Quick Replies, if included.
payload.message.metadata	Any additional metadata included with the message such as Tags.

Button types

Button type	Used for	Additional Properties	Description
link	Open website Send email Call phone number	url	Specify the URL of the: website to open phone number to call (including area code) email to send
postback	Start a passage	payload	The postback to start a passage. If the chatbot user presses this button, use this payload the same as you would for Quick Replies.
webview	Open a webview	url	The webview URL to open (including access token). The format of this URL is: `https://au.api.ingenious.ai/webview/v1/{teamId}/{botId}/{webviewId}?accessToken={token}` Your team and chatbot ID is available in general settings, and the webview ID is available from the webview menu.
		fallback	An alternate webview to open (including access token)
		size	The size to display the webview in the chat window, as per webview button.

{ 
  "app": { 
     "teamId": "xxxxxxxx", 
     "botId": "xxxxxxxxx" 
  }, 
  "webhook": { 
     "id": "xxxxxxxxxx", 
     "version": "v1" 
  }, 
  "events": [ 
     { 
       "id": "event_id", 
       "timestamp": 1458692752478, 
       "type": "conversation:message", 
       "payload": { 
          "conversation": { 
            "id": "{conversationId}" 
          }, 
          "message ":{
             "id":"xxxxxxxx",
             "author":{
                "type": "chatbot"
             },
             "content" : {
                "type":"button",
                "text":"Please choose an option:",
                "buttons": [
                  {
                    "text": "Open website",
                    "type": "link",
                    "url": "https://example.org"
                  },
                  {
                    "text": "Keep chatting",
                    "type": "postback",
                    "payload": {
                      "nextPassage": {
                         "passageId": "xxxxxxxx",
                         "inlineActions": []
                      }
                    }
                  },
                  {
                    "type": "link",
                    "text": "Call me!",
                    "url": "tel:+61404040404"
                  },
                  {
                    "type": "link",
                    "text": "Send an email",
                    "url": "mailto:test@email.com?cc=test2@email.com&bcc=test3@email.com&subject=Hello!&body=Hi"
                  },
                  {
                    "type": "webview",
                    "text": "Open a webview",
                    "url": "https://au.api.ingenious.ai/webview/v1/{teamId}/{botId}/{webviewId}?accessToken={token}",
                    "fallback": "https://au.api.ingenious.ai/webview/v1/{teamId}/{botId}/{webviewId}?accessToken={token}",
                    "size": "full"
                  }
                ]
             },
             "metadata" : {}
          }
        } 
     } 
  ] 
}

Carousel message

The chatbot sent a carousel with one or more carousel items. You must acknowledge this message.

Property	Description
payload.message.id	The unique identifier of the message.
payload.message.author.type	The author of type "chatbot".
payload.message.content.type	The content of type "carousel".
payload.message.content.items	An array of carousel cards. Each card is an object containing: "title" to display on the card. "subtitle" to display on the card. "imageUrl" for the image to display on the card. An array of up to three "buttons". Each button is defined as an object with the same properties as a button message.
payload.message.content.replies	An array of Quick Replies, if included.
payload.message.metadata	Any additional metadata included with the message such as Tags.

{ 
  "app": { 
     "teamId": "xxxxxxxx", 
     "botId": "xxxxxxxxx" 
  }, 
  "webhook": { 
     "id": "xxxxxxxxxx", 
     "version": "v1" 
  }, 
  "events": [ 
     { 
       "id": "event_id", 
       "timestamp": 1458692752478, 
       "type": "conversation:message", 
       "payload": { 
          "conversation": { 
            "id": "{conversationId}" 
          }, 
          "message ":{
             "id":"xxxxxxxx",
             "author":{
                "type": "chatbot"
             },
             "content" : {
                "type":"carousel",
                "items": [
                  {
                    "title":"Carousel Item 1",
                    "subtitle":"Item 1 subtltle",
                    "imageUrl": "https://example.org/image1.png",
                    "buttons": [
                      {
                        "text": "Open website",
                        "type": "link",
                        "url": "https://example.org"
                      },
                      {
                        "text": "Keep chatting",
                        "type": "postback",
                        "payload": {
                          "nextPassage": {
                             "passageId": "xxxxxxxx",
                             "inlineActions": []
                          }
                        }    
                      },
                    ]
                  },
                  {
                    "title":"Carousel Item 2",
                    "subtitle":"Item 2 subtltle",
                    "imageURL": "https://example.org/image2.png"
                    "buttons": [
                      {
                        "text": "Keep chatting",
                        "type": "postback",
                        "payload": {
                          "nextPassage": {
                             "passageId": "xxxxxxxx",
                             "inlineActions": []
                          }
                        }
                      },
                    ]
                  }
               ]
             },
             "metadata" : {}
          }
        } 
     } 
  ] 
}

Quick Replies

All message types may include an array of Quick Replies in the message content property.

To send a response that the chatbot user pressed a Quick Reply, send a postback request with the Quick Reply payload.

Property	Description
"type"	The type of "postback".
"text"	The text to display in the Quick Reply button.
"payload"	The payload of the passage to start and any actions to perform.

{ 
  "app": { 
     "teamId": "xxxxxxxx", 
     "botId": "xxxxxxxxx" 
  }, 
  "webhook": { 
     "id": "xxxxxxxxxx", 
     "version": "v1" 
  }, 
  "events": [ 
     { 
       "id": "event_id", 
       "timestamp": 1458692752478, 
       "type": "conversation:message", 
       "payload": { 
          "conversation": { 
            "id": "{conversationId}" 
          }, 
          "message ":{
             "id":"xxxxxxxx",
             "author":{
                "type": "chatbot"
             },
             "content" : {
                "type":"text",
                "text":"What's your favourite colour?",
                "replies":[
                  {
                    "type":"postback",
                    "text":"Green",
                    "payload": {
                      "nextPassage": {
                         "passageId": "zzzzzzzz",
                         "inlineActions": []
                      }
                    }                   
                  },
                  {
                    "type":"postback",
                    "text":"Blue",
                    "payload": {
                      "nextPassage": {
                         "passageId": "xxxxxxxx",
                         "inlineActions": []
                      }
                    }                    
                  }
                ]
             },
             "metadata" : {}
          }
        } 
     } 
  ] 
}