Mattermost integration: method and functional background

The Mattermost integration mirrors support web-chat conversations into a Mattermost channel, so the team can follow and answer the conversation from their own team messenger. In addition, i-Reserve can send notifications (such as booking confirmations or status changes) to specific channels. It talks to the Mattermost REST API v4.

Status: beta. The outbound direction (i-Reserve → Mattermost) works; the inbound direction (replies from Mattermost back into the conversation) is phase 2.

Authentication

The integration uses a bot account with a personal access token. A plain “incoming webhook” is not enough, because it cannot post messages in a thread — and threading is needed to keep each conversation neatly under one root message. For the inbound direction (phase 2) an outgoing-webhook token is also used to authenticate incoming requests.

Outbound (i-Reserve → Mattermost)

• Conversation started → a root post is created in the configured channel with the conversation id, visitor name and the page where the chat started.
• New message (visitor or agent) → posted as a threaded reply under that root post, with the sender's name. Attachments are uploaded and shown inline.
• Notification → per notification type you can map a target channel (e.g. booking confirmation to a separate channel). The message is posted standalone (not in a thread).

The conversation↔thread link is stored so follow-up messages land in the same thread. Sending is synchronous without retry; if the root post is gone, the integration self-heals (a next message recreates it).

Inbound (Mattermost → i-Reserve, phase 2)

An outgoing webhook in Mattermost sends replies in the thread to an i-Reserve endpoint. i-Reserve:

1. authenticates the request on the outgoing-webhook token (which also identifies the licence/owner);
2. looks up the matching thread/conversation via the root post id;
3. ignores messages from the bot itself (loop prevention);
4. maps the Mattermost user to an i-Reserve user (by e-mail; if that fails, the message is still recorded with the Mattermost name as author);
5. records the reply (including attachments) in the conversation.

Limitations

• The bot must be a member of every channel it posts to; otherwise a 403 follows.
• Sending is synchronous and is not retried on failure (it is logged).
• Inbound user matching is on exact e-mail address; no partial match.
• The inbound direction is phase 2 (beta) — for production rely on the outbound mirroring for now.