Canonical inbox and BlueGate messaging

Conversation model

• Direct iMessage threads use provider thread IDs like any;-;+15555555555.
• Group iMessage threads use the observed BlueGate/iMessage group chat GUID as the provider thread.
• Group conversations preserve participants, including the HomeForce sender and external participants, instead of collapsing into a direct thread.
• HomeForce contacts remain the identity layer; conversations and messages can link to contacts, participants, provider metadata, attachments, and status events.

Outbound messaging

• Direct sends use the configured BlueGate HomeForce provider endpoint.
• Production BlueGate send URLs should target the authenticated BlueGate provider/integration endpoint. Do not point HomeForce directly at BlueGate's public HomeForce webhook unless a signing layer adds BlueGate's timestamped HMAC headers.
• New group starts send selected participants through the BlueGate HomeForce provider endpoint and store the returned group chat GUID when BlueGate provides one.
• Existing group follow-ups with a real BlueGate chat GUID use the Partner V3 chat-scoped message route.
• HomeForce sends correlation metadata so BlueGate can status-sync the HomeForce message row back to sent, delivered, read, or failed.
• HomeForce validates that the selected contact is an active participant in the selected conversation before sending.
• Outbound SMS, email, call, and group-send routes are limited to workspace roles owner, agent, isa, and tc.

{
  "contact_id": "contact_123",
  "conversation_id": "conversation_123",
  "channel": "sms",
  "message_type": "imessage",
  "body": "Following up from HomeForce."
}

Inbound messaging

• BlueGate inbound sync carries chatGuid, providerChatGuid, isGroup, participants, and message status metadata.
• Direct inbound messages prefer the observed direct Mac chat ID over stale group correlation.
• Group inbound messages prefer the observed group chat GUID over cached direct-contact correlation.

BlueGate provider boundary

HomeForce stores a provider endpoint secret for inbound/status compatibility callbacks, integration credentials for new group/direct provider sends, and a BlueGate Partner V3 token for existing chat-scoped group sends, typing sessions, and attachment creation/upload. Provider configuration and provider-control actions are owner-only.

HomeForce can send configured headers, bearer tokens, or API-key headers to BlueGate. It does not automatically generate BlueGate public-webhook timestamped HMAC signatures, so production configs should use BlueGate's authenticated provider/Partner routes unless the configured gateway layer signs the request.

Known limitation

Text direct and group paths are live-tested. Attachment delivery depends on the BlueGate/Mac worker attachment download path and should be validated separately before customer use.