Contacts

The contact book is WaSphere's lightweight CRM. Every number that messages one of your sessions appears here automatically, and you can add numbers yourself before they have ever written to you.

What a contact holds

Field	Description
phone	Normalised digits, e.g. 447700900123
jid	The WhatsApp JID, e.g. 447700900123@s.whatsapp.net
whatsappName	The contact's WhatsApp profile name, refreshed on each inbound message
savedName	The name you set. Never auto-overwritten.
tags	CRM labels for segmenting — Lead, Customer, VIP, …
notes	A free-form private note about this contact
avatarUrl	Profile picture, when available

The split between whatsappName and savedName is deliberate. WhatsApp profile names change whenever the contact feels like it; your saved name is stable, and WaSphere will never overwrite it with whatever they renamed themselves to this week.

Tags and notes

Tags segment your book. A contact can hold up to 20, each up to 30 characters, and the workspace's distinct tags are listed for you so your vocabulary stays consistent rather than drifting into vip, VIP, and V.I.P..

Notes are a single free-form field per contact, up to 2000 characters — context an agent needs before replying: what they bought, what went wrong last time, what they prefer.

Both are visible from the contact panel in the Inbox, so an agent sees who they are talking to without leaving the thread. You can also message a contact directly from their card.

Finding contacts

The list supports free-text search across name and phone, and filtering by a single tag, with cursor pagination:

curl "https://api.yourdomain.com/workspaces/{workspaceId}/contacts?search=ali&tag=VIP&limit=50" \
  -H "Authorization: Bearer wsk_your_key"

Parameter	Notes
search	Free text, up to 100 characters
tag	Filter to one tag
limit	1–100
cursor	Pagination cursor from the previous page

List every tag in use:

curl https://api.yourdomain.com/workspaces/{workspaceId}/contacts/tags \
  -H "Authorization: Bearer wsk_your_key"

Adding and editing

Add a contact manually by phone number:

curl -X POST https://api.yourdomain.com/workspaces/{workspaceId}/contacts \
  -H "Authorization: Bearer wsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "447700900123", "savedName": "Ali Khan", "tags": ["Lead"] }'

Update the saved name, tags, or notes with PATCH /workspaces/{workspaceId}/contacts/{contactId}, and remove one with DELETE on the same path.

Bulk actions

Tag or delete many contacts in one call — up to 500 ids at a time:

curl -X POST https://api.yourdomain.com/workspaces/{workspaceId}/contacts/bulk \
  -H "Authorization: Bearer wsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["...", "..."],
    "action": "addTag",
    "tag": "Customer"
  }'

action is one of addTag, removeTag, or delete. The first two require tag.

CSV export

Export the whole book, or just a selection:

# Everything
curl -X POST https://api.yourdomain.com/workspaces/{workspaceId}/contacts/export \
  -H "Authorization: Bearer wsk_your_key" \
  -H "Content-Type: application/json" -d '{}'

# A subset (up to 10,000 ids)
curl -X POST https://api.yourdomain.com/workspaces/{workspaceId}/contacts/export \
  -H "Authorization: Bearer wsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["...", "..."] }'

CSV import

Bulk-load contacts from a CSV — up to 2000 rows per import. In the dashboard the columns are auto-detected (phone, name, tags, notes), with a value-sampling fallback that identifies the phone column when the header is unhelpful, and the parsed rows are previewed before anything is written.

curl -X POST https://api.yourdomain.com/workspaces/{workspaceId}/contacts/import \
  -H "Authorization: Bearer wsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone": "447700900123", "name": "Ali Khan", "tags": ["Lead"], "notes": "Asked about pricing" }
    ]
  }'

Import is additive and non-destructive: new numbers are added, numbers already in the book are skipped, and saved names and tags on existing contacts are never overwritten. Re-running the same import is safe. The CSV export round-trips back through import unchanged.

Access control

The contact book is gated by the contacts capability. Owners and Admins always have it; Agents have it only if their custom role grants it — see Team & Roles.

Related

• Inbox — contact tags, notes, and cards in the conversation view
• Team & Roles — who can see and edit the book
• Send messages — messaging the numbers you have collected