> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/product/features/integrations/guest-communications.md).

# Guest communications

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/guest-communications.md).
{% endhint %}

**Guest communications** connects Snapfix with **D3X**, an outside service that carries messages between a hotel and its **guests**. When a site is connected, D3X sends each new guest message to Snapfix as a webhook, and Snapfix passes it on as a live update to the site's **inbox** channel and as a push to the site's admins and inbox users. Snapfix keeps no inbox of its own, no app or web screen shows the messages, and the webhook creates no tasks \[[ASK-14](https://github.com/snapfix/docs/blob/main/ASK.md#ask-14-does-d3x-create-tasks-in-snapfix-today)]. The staging database has none of the inbox tables, so whether any site is connected today is open \[[ASK-157](https://github.com/snapfix/docs/blob/main/ASK.md#ask-157-is-the-d3x-inbox-live-and-should-its-webhook-accept-only-connected-sites)].

## Rules

### Connecting a site

* A site is connected only with the server command `inbox:setup`, which takes the site, the D3X key and secret, and an SLA time in minutes (30 by default). The repos do not say who runs it, or for which sites \[[ASK-157](https://github.com/snapfix/docs/blob/main/ASK.md#ask-157-is-the-d3x-inbox-live-and-should-its-webhook-accept-only-connected-sites)] (api\_php\_live\_v2 @ ef3c4319f6, `app/Console/Commands/InboxSetupCommand.php:13-73`).
* The command turns on the site's inbox switch and stores the key and the secret encrypted. The SLA time is stored, and no code reads it (`app/Models/Inbox/InboxConfigModel.php`).
* With the inbox switch off, the inbox channel and the inbox routes refuse everyone (`app/Policies/ParentPolicy.php:34-77`).
* No plan or subscription check applies to the inbox.

### Who sees the inbox

* Site admins see the inbox. Other members see it only with the inbox view-only or inbox full-access permission; full access, together with the right to operate the site, lets them change the site's automation rules (`ParentPolicy.php:34-77`).
* The automation rules are listed, created, changed and deleted under `/v1/app/inbox/{parentUuid}/automation-rules`. They are saved, but nothing applies them, and no app calls the routes \[[ASK-14](https://github.com/snapfix/docs/blob/main/ASK.md#ask-14-does-d3x-create-tasks-in-snapfix-today)] ([Integrations API](https://docs.snapfix.com/engineering-reference/api/integrations.md)).

### Messages

* D3X calls [`POST /v1/d3x/webhook`](https://docs.snapfix.com/engineering-reference/api/integrations.md#post-v1d3xwebhook) with one shared secret, for every site, in the `X-D3x-Webhook-Secret` header. The site comes from the request's `parent_uuid` and is checked against no table \[[ASK-157](https://github.com/snapfix/docs/blob/main/ASK.md#ask-157-is-the-d3x-inbox-live-and-should-its-webhook-accept-only-connected-sites)].
* Today the webhook answers `500` to every call: after it queues an accepted event, and instead of `401` for a missing or wrong secret, or when no secret is configured. An accepted event is still processed.
* Only `message.received` events do anything. `task.trigger`, `escalation` and `thread.updated` events are accepted and ignored \[[ASK-14](https://github.com/snapfix/docs/blob/main/ASK.md#ask-14-does-d3x-create-tasks-in-snapfix-today)] (`app/Jobs/Inbox/ProcessD3xWebhook.php:49-55`).
* Each event ID is handled once within 24 hours; a repeat does nothing, and an event without an ID is not handled (`ProcessD3xWebhook.php:41`, `:62-73`).
* A message goes to the site's private inbox channel, which only people who may view the inbox can subscribe to. No app or web code subscribes to it (`app/Events/Inbox/InboxMessageReceived.php:28-31`, `routes/channels.php:22-25`).
* It also goes as a push to the devices of the site's admins and of members with an inbox permission, who are not deleted. The push reads "New Guest Message" and " sent a message", or "Guest sent a message" without a name. No app has an inbox screen, so the push is all a person sees (`app/Jobs/Inbox/SendInboxFcmNotification.php:108-141`).
* The push goes out even when the site's inbox switch is off.
* The push's data field carries the whole message data that D3X sends, and iOS shows the guest's name on the notification. What guest data a push may carry is open \[[ASK-158](https://github.com/snapfix/docs/blob/main/ASK.md#ask-158-what-guest-data-may-a-push-carry)] (`app/Notifications/FeatureFcmNotification.php:50-87`).
* The push job tries to write the push body, with the guest data and the device tokens, to the notification log, but the write always fails, so nothing is logged today; once the write works, the log would keep the guest data.

### Replies and tasks

* Snapfix sends no reply to a guest. A D3X client that can send replies, close and archive threads and mark them read is set up in the code, but nothing calls it (`app/Providers/AppServiceProvider.php:50-51`).
* The webhook creates no tasks: its task trigger is commented out \[[ASK-14](https://github.com/snapfix/docs/blob/main/ASK.md#ask-14-does-d3x-create-tasks-in-snapfix-today)] (`ProcessD3xWebhook.php:51`). Tasks made through the [vendor API](https://docs.snapfix.com/product/features/integrations/vendor-api.md) carry origin 11, which Snapfix's housekeeping counts treat as D3X tasks.

## Flow

```mermaid
flowchart TD
  d3x["D3X sends a webhook"] --> secret{"Secret header right?"}
  secret -- "no, or no secret configured" --> refused["500, nothing queued"]
  secret -- "yes" --> queued["Event queued; the answer is still 500"]
  queued --> repeat{"Event ID seen in the last 24 hours?"}
  repeat -- "yes" --> ignored["Nothing done"]
  repeat -- "no" --> kind{"message.received?"}
  kind -- "no" --> dropped["Ignored"]
  kind -- "yes" --> live["Live update to the site's inbox channel"]
  kind -- "yes" --> push["Push to admins and inbox members"]
  live --> none["No app or web screen shows it"]
  push --> none
```

## Platforms

| Capability                         | Web                                                                                                            | iOS                          | Android                                       |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------- |
| Connect a site to D3X              | No; server command only                                                                                        | No                           | No                                            |
| See guest messages                 | No                                                                                                             | No                           | No                                            |
| Get the live update                | No; no client subscribes                                                                                       | No                           | No                                            |
| Get a push for a guest message     | No                                                                                                             | Yes, with the title and text | Data only; no app code handles the inbox type |
| Manage automation rules            | No; API only                                                                                                   | No                           | No                                            |
| Create a task from a guest request | No \[[ASK-14](https://github.com/snapfix/docs/blob/main/ASK.md#ask-14-does-d3x-create-tasks-in-snapfix-today)] | No                           | No                                            |

## Screens

* None. No screen shows the inbox, the messages or the automation rules ([Integrations screens](https://docs.snapfix.com/how-the-apps-work/screens/integrations.md)).

## API and data

* [`POST /v1/d3x/webhook`](https://docs.snapfix.com/engineering-reference/api/integrations.md#post-v1d3xwebhook): receives one D3X event. Called by D3X, external.
* [Integrations API](https://docs.snapfix.com/engineering-reference/api/integrations.md): the inbox automation rule routes (no caller) and `/broadcasting/auth`, which authorizes a subscription to the inbox channel.
* Tables: `tPri_Inbox_Config` (the D3X key and secret, encrypted), [`tPri_SettingsParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_settingsparent.md) (the inbox switch), [`tPri_UserParent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_userparent.md) (each member's inbox permissions) and [`tPri_Log_NotifAPIRequests`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_notifapirequests.md) (the push log). The staging database has no inbox table and no inbox switch column yet: the migrations that add them are from June 2026.

## Depends on

* [Push notifications](https://docs.snapfix.com/product/features/notifications/push-notifications.md): the pushes to devices and the push log.
* [Site users](https://docs.snapfix.com/product/features/console/site-users.md): the admin role and the inbox permissions that decide who gets the push.
* [Vendor API](https://docs.snapfix.com/product/features/integrations/vendor-api.md): the origin-11 tasks counted as D3X tasks.

## Edge cases

* **Repeated delivery:** a repeat within 24 hours is ignored; after that the same event ID would be handled again.
* **Event with no ID or a missing field:** not handled; a missing required field fails before anything is logged or queued.
* **Unknown site:** no admin is found, so no push goes out.
* **Site with the inbox switch off:** no one can subscribe to the live update, but the push still goes out.
* **Guest name on a lock screen:** the iOS push shows the guest's name \[[ASK-158](https://github.com/snapfix/docs/blob/main/ASK.md#ask-158-what-guest-data-may-a-push-carry)].
* **Message history:** Snapfix stores no guest messages; D3X holds them.
* **Time zones:** none. The event's timestamp is passed on as D3X sends it, with no unit set in the code.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/product/features/integrations/guest-communications.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
