Scope Wiser API: Managing Subscribers, Labels and Sequences
Create, read, update and delete contacts through the API, then label them, put them in sequences, store custom fields, assign a chat to a colleague, add internal notes and mark a conversation resolved.
These endpoints keep Scope Wiser's contact list in step with whatever system you treat as the source of truth — a CRM, a shop, a booking system. Read Scope Wiser API: Overview and Authentication first for the base URL and the apiToken parameter.
Every endpoint here takes phone_number_id (your WhatsApp number) and phone_number (the customer's), unless noted.
Reading contacts
One contact — POST → /whatsapp/subscriber/get
Returns subscriber_id, chat_id, names, email, gender, created_at, the assigned agent, the bot and AI reply states, and label_names.
Many — GET or POST → /whatsapp/subscriber/list
Parameter | Notes |
|---|---|
| Required, up to 100 |
| Page number, from 1 |
|
|
Keep calling while nextOffset is returned. Use orderBy=1 when you want people who have been in touch lately rather than the whole list.
Creating a contact
POST → /whatsapp/subscriber/create
Watch the parameter names. This endpoint alone uses camelCase:
Parameter | Notes |
|---|---|
| Not |
| Not |
| Required |
curl -X POST \
'https://connect.scopewiser.com/api/v1/whatsapp/subscriber/create' \
-d 'apiToken=API-KEY' \
-d 'phoneNumberID=PHONE-NUMBER-ID' \
-d 'name=NAME' \
-d 'phoneNumber=MOBILE'Creating a contact does not give you permission to message them, and it does not open a 24-hour window. Until they message you, only an approved template will reach them.
Expect these failures: the account was not found, the subscriber already exists, or your plan's subscriber limit is full.
Updating and deleting
Update — POST → /whatsapp/subscriber/update, with any of first_name, last_name, gender, label_ids. All optional; send only what changed.
Delete — GET or POST → /whatsapp/subscriber/delete. This removes the contact and their history. There is no undo, so guard it in your own code.
Reset a form — POST → /whatsapp/subscriber/reset/user-input-flow. Clears a half-finished User Input Flow so the customer can start it again — the fix for someone stuck mid-form.
Labels
Labels are how Scope Wiser groups people, and they are what makes a targeted broadcast possible later. Labels, Lists and Segments covers the thinking; these are the endpoints.
Action | Endpoint |
|---|---|
List labels |
|
Create a label |
|
Assign to a contact |
|
Remove from a contact |
|
label_ids is a comma-separated list, for example 1,4,5. Call /label/list first to map your own names onto ids, and cache the result — do not look it up on every request.
Labelling from your own system is the highest-value thing on this page. A shop that labels purchased-this-month as orders come in can send a relevant broadcast; one that does not can only message everybody.
Sequences
Action | Endpoint |
|---|---|
List sequences |
|
Enrol a contact |
|
Remove a contact |
|
Removing someone matters as much as adding them. When an order is paid, take that customer out of the abandoned-cart sequence — otherwise they are chased for something they have already bought.
Custom fields
Action | Endpoint |
|---|---|
List the fields |
|
Set values |
|
custom_fields is a JSON object keyed by field name:
-d 'custom_fields={"customer_name":"John","customer_email":"john@example.com"}'The list endpoint returns each field's id, name and reply_type, so you can check a field exists and holds the type you expect before writing to it. Values written here can be used in message templates and flow replies — see Bot Error Logs and Custom Fields.
Inbox actions
These do the same things your team does by hand in the Shared Inbox.
Assign a chat — POST → /whatsapp/subscriber/chat/assign-to-team-member with team_member_id. Get ids from /users/team-member/list.
Mark a conversation — POST → /whatsapp/subscriber/chat/mark-conversation with action, one of resolved, reopen, archived, unarchived, blocked, unblocked.
The stored status maps like this:
Value | Meaning |
|---|---|
| Open — the result of reopen, unarchived or unblocked |
| Resolved |
| Archived |
| Blocked |
Add an internal note — POST → /whatsapp/subscriber/chat/add-notes with note_text. Notes are for your team; the customer never sees them. Writing the order number or ticket reference here as your system creates it saves an agent hunting for it later.
A sensible sync
A workable pattern for keeping a CRM and Scope Wiser aligned:
On a new customer, call subscriber/create. Treat "already exist" as success, not an error.
Write what you know with assign-custom-fields.
Apply state as a label with assign-labels —
trial,paid,lapsed.When state changes, remove-labels the old one before assigning the new. Nothing does this for you, and stale labels quietly ruin targeting.
On a purchase, remove-sequence for any nurture they no longer belong in.