Associated Number

CRUD for the PSTN and WhatsApp numbers a user can send from.

This is a prerequisite for WhatsApp messaging. sendWhatsAppMessage() needs an associatedNumberId, and the only way to get one is to create a "WHATSAPP" associated number here first and use its id. There is no default — you cannot send a WhatsApp message until at least one exists.

Requires the associated_number capability.

Creating a number

Both kinds share the same fields; only the ones below differ by type.

// PSTN
const pstn = await kasookoo.createAssociatedNumber({
    associatedNumber: "+15551234567",   // E.164 — mandatory
    userId: "user_123",                 // mandatory
    numberType: "PSTN",                 // mandatory
    label: "Support line",              // mandatory
    country: "pakistan",                // optional
    isEnable: true,                     // optional
    isPrimary: true,                    // optional
})

// WhatsApp
const whatsapp = await kasookoo.createAssociatedNumber({
    associatedNumber: "+447700900123",  // mandatory
    userId: "user_123",                 // mandatory
    numberType: "WHATSAPP",             // mandatory
    label: "WhatsApp support",          // mandatory
    whatsappNumberId: "whatsapp_phone_number_id",   // mandatory for WHATSAPP — from your WhatsApp Business setup
})

Field	Required?	Notes
`associatedNumber`	Always	The phone number, E.164 format.
`userId`	Always	Who this number belongs to.
`numberType`	Always	`"PSTN"` or `"WHATSAPP"` — nothing else. Can be changed later via update — e.g. converting PSTN to WhatsApp.
`label`	Always	Display label, e.g. `"Support line"`.
`whatsappNumberId`	Only if `numberType` is `"WHATSAPP"`	Your WhatsApp Business phone number id. Must be omitted entirely when `numberType` is `"PSTN"` — providing it throws, same as omitting it for WhatsApp.
`country`, `city`, `prefix`	Optional	Descriptive metadata. Same fields work for either type.
`isTollFree`, `isEnable`, `isPrimary`	Optional	Same fields work for either type.

The SDK checks the numberType / whatsappNumberId pairing itself and throws invalid_params before any request goes out — a bad numberType or a mismatched whatsappNumberId never reaches the backend.

Updating a number

Every field is optional on update — only what you pass is changed, everything else on the record stays as it was:

await kasookoo.updateAssociatedNumber(pstn.id, {
    label: "Updated label",
    isPrimary: false,
})

numberType can be changed — a PSTN number can be converted into a WhatsApp one, or back:

// Convert a PSTN number into a WhatsApp one
await kasookoo.updateAssociatedNumber(pstn.id, {
    numberType: "WHATSAPP",
    whatsappNumberId: "new_whatsapp_id",   // mandatory together with numberType: "WHATSAPP"
    label: "Now used for WhatsApp",
})

// Convert back to PSTN — whatsappNumberId must be omitted, not set to something falsy
await kasookoo.updateAssociatedNumber(whatsapp.id, {
    numberType: "PSTN",
})

Whenever numberType is set to "WHATSAPP" — in createAssociatedNumber() or here — whatsappNumberId is mandatory in that same call. Setting numberType to "PSTN" forbids it, for the same reason. The SDK checks this itself and throws invalid_params before any request goes out.

If you omit numberType entirely (the common case — changing some other field on an existing number), whatsappNumberId is sent exactly as given, with no consistency check, since the SDK doesn't know the record's current type without being told.

Deleting and listing

await kasookoo.deleteAssociatedNumber(pstn.id)

const { items, total } = await kasookoo.getAssociatedNumbers({ numberType: "WHATSAPP", skip: 0, limit: 100 })

getAssociatedNumbers() is read-only — nothing is cached, call it again for fresh data. numberType, skip and limit are all optional; omit numberType to get both kinds back together.