Skip to content

Chats

Menu Location: Chats (top-level nav icon, only shown when Brinks SMS is enabled) (brinks-conversations.php)

Last Updated: 2026-07-20

Overview

Chats is the inbox for two-way SMS text conversations with customers, handled by your AI text assistant ("Brinks"). It shows every customer who has texted in, whether the AI or a human admin is currently handling the thread, and lets you take over, reply, and hand the conversation back to the AI.

Primary Functions:

  • View all customer SMS conversations in one inbox
  • See at a glance whether the AI or a human admin is handling each conversation
  • Take over a conversation from the AI ("handoff") and reply as a human
  • Mark a conversation complete, which returns it to auto-replies
  • See who sent each admin reply and why an outbound text failed to deliver

Page Layout

Three-pane layout:

  • Left (filter nav): Open, Unread, Completed, Automated, All chats, each with a live count
  • Middle (conversation list): one row per customer, with avatar, name, last message preview, timestamp, and a badge showing who's handling it (human / AI / completed)
  • Right (conversation thread): the full message history for the selected customer, with a reply box at the bottom. In the reply box, pressing Enter inserts a line break (so you can compose multi-line messages); click Send to actually send the message

Handoff States

  • Automated (bolt icon): the AI is replying to this customer, no admin action needed
  • Open (person icon): a human admin has taken over ("handoff"), the AI stops auto-replying
  • Completed (check icon): the conversation was handed back and marked resolved
  • Unread: an Open conversation with a new incoming message since you last viewed it

Sending a reply as an admin automatically takes the conversation over (sets it to Open). While a conversation is Open, a Mark Complete button on the thread returns it to auto-replies and moves it to Completed in one step. From Completed or Automated, a Take Over button hands it back to a human (Open).

Message Attribution

Each message bubble in the thread shows who sent it:

  • Customer replies: the customer's name and avatar (a Gravatar identicon matching the one shown in the conversation list)
  • AI replies: labeled "AI"
  • Admin replies: labeled with the sending admin's full name, with their Gravatar avatar (based on their admin email). Admin messages sent before this attribution existed fall back to showing your company name.
  • Test messages (dev/localhost only): labeled "Test"

Delivery Failure Reasons

If an outgoing text fails or is undelivered, the status now shows a plain-English reason next to "Failed"/"Undelivered" (for example, "Invalid phone number", "Recipient texted STOP and is unsubscribed", "Carrier flagged the message as spam and filtered it"), based on the delivery error Twilio reported. Messages with no specific error code just show the plain status.

Common Use Cases

Use Case 1: Take Over a Conversation

Goal: Step in and answer a customer directly instead of letting the AI reply

Steps:

  1. Open Chats and find the customer (search or browse Automated/All)
  2. Open their conversation thread
  3. Type a reply and send. This automatically hands the conversation to you (Open)
  4. Continue replying as needed; the AI will not respond while it's in your hands

Use Case 2: Close Out a Conversation You've Taken Over

Goal: Finish handling a conversation and hand it back to the AI

Steps:

  1. Open the conversation (it should be in Open or Unread)
  2. Click Mark Complete on the thread. This returns the conversation to auto-replies and moves it to Completed
  3. Confirm it moves out of Open/Unread and into Completed

Use Case 3: Investigate a Failed Text

Goal: Find out why a customer didn't receive a message

Steps:

  1. Open the customer's conversation
  2. Find the failed/undelivered message. The reason is shown next to the status (e.g. carrier block, invalid number, opted out)
  3. Act accordingly (correct the phone number, respect an opt-out, or contact the customer another way)

Troubleshooting

A message shows "Undelivered" or "Failed" with no reason

Twilio didn't report a specific error code for that message; only the status is shown.

An admin reply shows the company name instead of a person's name

The message was sent before admin attribution was added, or was sent by a process with no logged-in admin session (id 0).

  • Customer SMS History (customer-sms.php): same conversation view, scoped to a single customer, opened from their Customer Detail page
  • SMS Messages (sms-pending.php): the outbound SMS queue and delivery stats across all customers

Recent Updates

2026-07-21

  • Changed: pressing Enter in the reply box now inserts a line break instead of sending; use the Send button to send the message. This makes multi-line texts easier to compose

2026-07-20

  • New: outbound message delivery failures now show a plain-English reason (from Twilio's error code) instead of just "Failed"/"Undelivered"
  • New: admin replies are attributed to the specific admin who sent them (name + Gravatar avatar), not just the company name
  • Customer avatars in the thread now match the identicon shown in the conversation list