Manage contacts and conversations in your Paige bot

Every time someone messages your bot, Paige records the conversation and links it to their phone number. The Conversations section of your project dashboard gives you a live view of who is talking to your bot, what state each conversation is in, and the full message history. You can also intervene manually — taking a conversation over from your bot and replying yourself — without touching your bot code.

​

Contacts

A contact is one person who has messaged your bot. Paige creates the record automatically the first time a message arrives. Each contact can have multiple conversations over time. From the contacts list you can:

• Browse all contacts that have messaged your bot
• View all conversations for a specific contact
• See the full message history across a contact’s conversations

​

Phone numbers and usernames

WhatsApp is moving to usernames, so a contact isn’t always a phone number. Paige recognises a person by their number, by a WhatsApp-issued ID, or both:

• Phone only — someone you imported, or who messaged before usernames existed.
• Phone and ID — most people, once they’ve messaged you.
• Username only — someone who’s adopted a WhatsApp username and hasn’t shared a number. They show as @name in your contacts list.

You don’t manage any of this. When someone you imported messages you for the first time, Paige links the two automatically rather than creating a second contact. Two practical consequences worth knowing:

• A contact you imported can be broadcast to, but not chatted with until they message you — you have a number, but nothing to attach a conversation to yet.
• A username-only contact is the reverse: you can chat with them, but Broadcasts can’t reach them, because a broadcast needs a phone number. Some message types also don’t work for them, and you’ll see an error under the message saying so.

​

Conversations

A conversation is a session between your bot and a contact. Each conversation has:

• A reference to the contact (phone number)
• A state — the current position in your bot’s state machine
• A full log of inbound and outbound messages

​

Conversation state

The state field reflects where the contact is in your bot’s conversation flow. It is set and updated by your bot code as the contact progresses through the state machine. For example, a contact might move from unstructured → collect_info → support depending on what your bot does.

​

Changing state from the dashboard

There’s no general-purpose “set this conversation’s state” control. State is your bot’s to manage, and the dashboard only lets you set it at one specific moment: when you hand a conversation back after taking it over. Click Handover ON on a conversation that’s in handover and you’re asked to pick the state to resume from. That picker is the only place the dashboard writes a state, and it deliberately leaves out handover, end, and finish — you can’t hand a conversation back into handover, or into a terminal state. See Taking over from your bot below and the Conversations tab. To move a conversation that isn’t in handover, take it over first, then hand it back to the state you want.

​

Filtering by state

The conversations list can be filtered by state. Use the All states dropdown to view only conversations in a particular state — for example, all contacts currently in collect_info or all contacts in a custom awaiting_payment state. You can also fetch the list of unique states currently active across all conversations. This is useful for getting a quick overview of where your contacts are in the conversation flow.

​

Taking over from your bot

Sometimes a bot should get out of the way — the customer is upset, the request is unusual, or they’ve asked for a person. Handover is how you step in. Click Handover at the top of a conversation and your bot stops responding to that contact entirely. It doesn’t try to help, doesn’t half-answer, doesn’t run at all. Messages still arrive and are still recorded; they just wait for you. The contact gets an orange marker in the list so you can see at a glance who’s waiting.

​

Handing back

Turning handover off is a little more involved than turning it on, and it’s worth knowing why. Click Handover ON and you’re asked to pick a conversation state to hand back to — there’s no plain “give it back to the bot” button. That’s because your bot needs to know where the conversation is when it resumes. Dropping it back mid-flow with no state would leave it confused. Picking a state — usually your bot’s default, like unstructured — tells it where to pick up.

​

The 24-hour window

WhatsApp only lets a business message a customer freely for 24 hours after that customer’s last message. This is Meta’s rule, not Paige’s, and it applies to everything you send from the dashboard. Once the window closes, the message box is disabled and shows 24-hour messaging window has expired, and the handover control reads 24h expired. To reach the contact after that you need an approved message template.

​

Media customers send you

Photos, PDFs, and voice notes appear inline in the conversation. If you’ve turned on media capture in Save from Conversations mode, each one gets a Save to Storage button so you can keep the ones that matter — a proof of payment, a signed form — before WhatsApp drops them after about 30 days.

​

How conversations are recorded

Paige logs messages automatically as your bot handles them. Every inbound message your bot receives and every outbound message it sends is stored in the database and associated with the correct conversation — you do not need to write any logging code yourself.

​

Replying from the dashboard needs a small addition to your bot

Reading conversations works out of the box. Sending from the dashboard needs a piece of code in your bot that receives the message and passes it to WhatsApp — and that isn’t there by default. You’ll find Conversations listed in Tools → Connectors. It sits alongside Airtable and Slack, but it works differently from both: there’s no account to sign in to and no token to paste. Clicking Connect simply asks the Code agent to add the necessary file to your bot. Once it has, the message box works. If you’d rather just ask, this does the same thing:

“Install the conversations module so I can send messages from the dashboard.”