Skip to content
PaalChat Docs

Common workflows

Contacts and conversations

The people a business talks to and its conversations with them - kept by PaalChat, read and worked through the API.

.md

In a nutshell

PaalChat keeps a contact for everyone a business messages or hears from, and one conversation per business number and contact. Read them, add your own ids, fields and tags, work conversations (status, priority, tags, read, notes), and listen for contact.* and conversation.* events.

What PaalChat keeps

  • Contacts - created automatically by the first message in or out (named from the person's WhatsApp profile), or by you. Each has its identities (how it is reached: WhatsApp number today), your own external_id, the business's custom fields and tags.
  • Conversations - one per business number and contact. Every message, in and out, belongs to one (conversation_id on messages and their callbacks).
  • Message content - what was said, encrypted, for the conversation history (how long).

How messages join conversations

Text
 customer writes ──▶ open ──(you resolve)──▶ resolved ──(customer writes)──▶ open
 you write first ──▶ pending ──(customer replies)──▶ open
 closed ──(next message)──▶ a new conversation
  • An incoming message joins the current conversation on that number, reopening it if it was pending, resolved or snoozed, and adds to unread_count.
  • A send joins the current conversation, or starts a pending one - so a broadcast does not fill your inbox with open conversations.
  • window_open says whether free-form text is allowed (the contact wrote in the last 24 hours to that number).

Link contacts to your records

cURL
curl -X POST https://whatsapp.paaltech.org/api/v1/businesses/presec/contacts \
  -H "Authorization: Bearer $PAALCHAT_TOKEN" -H "Content-Type: application/json" \
  -d '{"external_id": "parent-77", "phone": "+233241234567", "name": "Ama Mensah", "tags": ["parent"]}'

The contact is matched by external_id, else by phone, else created. Define the business's own fields first (Define a contact field), then set them with custom_fields.

Work a conversation

Events

Event When
contact.created A contact's first message in or out, or you created it
contact.updated Its details, fields or tags changed
conversation.created A conversation started
conversation.updated Status, priority, tags or assignee changed, or the contact reopened it

New messages alone arrive as message.received / message.status, not as conversation.updated.