Portal Messaging

Portal Messaging provides a threaded conversation system between your team and your portal contacts. Contacts can start new conversations, reply to existing threads, and receive replies from your team, all within the portal interface.

Requirements

• Portal must be enabled on the tenant.

• Messaging must be enabled: The portal_messages_enabled tenant setting must be true (this is the default). When disabled, all messaging endpoints return 404 and the Messages navigation item is hidden.

• Contact must have portal access enabled.

How Messaging Works

Conversation Model

Messaging is organized around conversations (threads). Each conversation has:

• Subject: A short description of the topic (set when the conversation is created).

• Status: Either "open" or "closed". Open conversations accept new replies.

• Contact: The portal contact who owns the conversation.

• Messages: An ordered list of messages within the thread.

Message Flow

1. A portal contact creates a new conversation with a subject and an initial message.

2. The conversation appears in both the portal contact's message list and your team's admin interface.

3. Your team replies from the admin side. The reply appears as a message in the conversation thread.

4. The portal contact sees the reply in their conversation view, marked as from your company.

5. The contact can reply back, continuing the thread.

6. This continues until either party closes the conversation.

Sender Identity

• Portal contact messages: Identified by the contact's first name and marked as "from you" in the portal view.

• Team messages: Displayed with your tenant's company name as the sender (e.g., "Acme Corp"). Individual team member names are not shown to the portal contact.

Using Messages as a Portal Contact

Viewing Conversations

1. Click Messages in the portal navigation.

2. The conversations list shows all conversations for the logged-in contact, sorted by most recent activity.

Each conversation in the list displays:

• Subject: The conversation topic.

• Status: Open or closed.

• Last message date: When the most recent message was sent.

• Unread count: Number of unread messages from your team.

• Latest message preview: A truncated preview (first 100 characters) of the most recent message, with an indicator of whether it was sent by the contact or the team.

A total unread message count is shown at the top of the page.

Reading a Conversation

1. Click a conversation in the list to open it.

2. The full message thread is displayed in chronological order (oldest first).

Each message shows:

• Sender name: The contact's first name (for their messages) or the company name (for team messages).

• Message body: The full text of the message.

• Timestamp: When the message was sent.

• From-you indicator: Messages from the contact are visually distinguished from team messages.

When you open a conversation, all unread messages from the team are automatically marked as read.

Starting a New Conversation

1. From the Messages page, click New Conversation (or equivalent button).

2. Enter a subject (required, up to 255 characters). Choose something descriptive like "Question about March invoice" or "Need updated hosting credentials".

3. Enter the message body (required, up to 5,000 characters).

4. Click Send.

The conversation is created with "open" status, and you are redirected to the conversation thread view.

Replying to a Conversation

1. Open the conversation.

2. Type your reply in the message input field (up to 5,000 characters).

3. Click Send.

Your reply is added to the thread. The conversation's last-message timestamp is updated, and the status is set to "open" (in case it was previously closed).

Using Messages as an Admin

Viewing Portal Conversations

Portal conversations are accessible from the admin interface through the portal conversation management area. Your team can see all conversations across all portal contacts for your tenant.

Replying from the Admin Side

When your team replies to a portal conversation:

• The reply appears in the contact's conversation thread.

• The sender is displayed as your company name in the portal view.

• The message increments the contact's unread count until they open the conversation.

Conversation Status

• Open: The conversation is active. Both parties can send messages.

• Closed: The conversation is resolved. When a portal contact replies to a closed conversation, it is automatically reopened (status set back to "open").

Unread Tracking

Unread status is tracked per-message using a read_at timestamp:

• When a team member sends a message, it starts with read_at = null for the portal contact.

• When the portal contact opens the conversation, all unread team messages are marked as read (read_at set to the current time).

• The unread count on the conversations list reflects messages from the team that the contact has not yet viewed.

Messages sent by the portal contact are not counted as "unread" for the contact (they are the ones who sent them).

Message Constraints

Messages are plain text. Rich formatting (HTML, markdown) is not supported in portal messages.

Notifications

Portal Side

• The unread message count appears on the portal dashboard's metric cards.

• The Messages navigation item may show a badge with the total unread count.

• The conversations list shows per-conversation unread counts.

Admin Side

• Conversations from portal contacts appear in your team's admin interface.

• Your notification preferences determine how your team is alerted to new portal messages.

File Attachments

Messages can optionally reference a file via the file_id field. This allows a message to link to a shared file. File attachments follow the same visibility rules as the Files portal feature, the file must be shared with the portal contact.

Privacy and Data Scoping

• Each conversation belongs to a single contact. Other portal contacts at the same company cannot see each other's conversations.

• All messages within a conversation are visible to the contact and your admin team.

• Message data is scoped to the tenant. Cross-tenant access is not possible.

• Message content is included in GDPR data exports if the contact requests one (via the activities export).

Troubleshooting

Messages section not visible in portal

• Verify the portal_messages_enabled setting is true on the tenant.

• Check that the contact has portal access enabled.

Contact not receiving replies

• Ensure your team is replying to the correct conversation.

• The contact must open the conversation in the portal to see new messages, there is no push notification to the contact's email for message replies.

"404" when accessing messages

• The messaging feature is disabled on the tenant. Enable portal_messages_enabled in tenant settings.