Application owners

Codes need nothing from the merchant: your backend sends them and you pay. WhatsApp is different. A WhatsApp Business Account belongs to the merchant’s Meta business, only the merchant can connect it, and only the merchant’s people should read their customers’ conversations. So an application that needs WhatsApp is handed to its owner, the way Meta’s solution partners onboard a customer: you invite, the merchant accepts under your configuration, and the application stays yours.

Who does what after a handover

	You (the partner)	The owner (the merchant)
Billing, price, balance	Yours, unchanged.	Nothing.
The `tk_partner_` key, the partner webhook, verify settings, the brand, review	Yours.	Never shown.
Sending codes and messages through the API	Yours, with `application` as before.	No API.
The WhatsApp number	Read its state and the message log.	Connects their own number from their dashboard, disconnects it.
Templates	Create and edit them.	Create and edit them.
The inbox and the team	Add and remove agents on the application’s team.	Runs the inbox with their team.
Usage and the brand	Yours.	Read-only.
Deleting the application	Nobody.	Cannot.

The owner’s dashboard shows the application as coming through your partner name, and its brand line reads their name with yours beside it.

The flow

Invite by phone

POST /v1/partner/applications/{external_id}/owner with the person’s name and Saudi mobile, optionally their email and the locale of the message (ar by default).

curl -X POST https://tawked.com/v1/partner/applications/store_88/owner \
  -H "Authorization: Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "أحمد", "phone": "0551234567", "email": "ahmed@example.com", "locale": "ar" }'

The answer is 201 with the invitation and, once only, the link:

{
  "external_id": "store_88",
  "owner": {
    "status": "invited",
    "name": "أحمد",
    "phone": "+966551234567",
    "email": "ahmed@example.com",
    "invited_at": "2026-09-17T08:00:00+00:00",
    "expires_at": "2026-09-24T08:00:00+00:00",
    "accepted_at": null
  },
  "accept_url": "https://tawked.com/ar/invite/kq3v…"
}

Tawked sends the same link by SMS to the invited phone, under Tawked’s name, naming you and the application. Show accept_url in your own app too if you like; it is not returned again.

The merchant accepts

The link opens a page that names you, the application and the masked phone. The merchant signs in to Tawked with that very phone through the ordinary one-time code, and the acceptance happens on sign-in. A phone new to Tawked gets an account with the name and email from the invitation and skips the onboarding wizard: the handed-over application is its first, and you already reviewed the brand. A forwarded link is useless to anyone else, because the invited phone is the credential.

You are told

service.owner_accepted arrives at your partner webhook with the owner’s name, phone and accepted_at, and GET /v1/partner/applications/{external_id}/owner answers accepted from then on. The merchant lands on the application’s WhatsApp tab and connects their number.

Read the state

GET /v1/partner/applications/{external_id}/owner answers one of three states:

`owner.status`	Meaning	Fields set
`none`	Never handed over, or taken back.	None; every other field is `null`.
`invited`	An invitation is pending.	`name`, `phone`, `email`, `invited_at`, `expires_at`.
`accepted`	The owner runs the business side.	`name`, `phone`, `email`, `invited_at`, `accepted_at`.

The rules

One pending invitation per application. Inviting again supersedes the pending one; only the newest link works.
The invitation expires after 7 days. After that the link says so and the state goes back to none. Invite again.
The phone is the credential. It must be a Saudi mobile in an accepted format. It may be new to Tawked or belong to the owner of a client account, never to one of your own users or to a member of another team (409 phone_not_eligible).
Nothing changes hands while a WhatsApp number is connected, in either direction (409 number_connected). The inbox belongs to the team that runs the application, so the number is disconnected first, or you invite before it is connected. Accepting is refused too if a number was connected after the invitation went out.
One owner at a time. Inviting someone else while an owner is in place answers 409 owner_already_assigned; revoke first.
Each invitation is an SMS, capped at 3 an hour per application and 100 a day per partner (429 rate_limited). Nothing is written or sent over the cap.

Take it back

DELETE /v1/partner/applications/{external_id}/owner withdraws a pending invitation, or removes an accepted owner: their account and its agents lose access to the application at once, and service.owner_revoked fires. Billing and keys never moved, so nothing else changes. Refused with 409 number_connected while a number is live.

curl -X DELETE https://tawked.com/v1/partner/applications/store_88/owner \
  -H "Authorization: Bearer tk_partner_xxxxxxxxxxxxxxxxxxxx"

{
  "external_id": "store_88",
  "owner": { "status": "none", "name": null, "phone": null, "email": null, "invited_at": null, "expires_at": null, "accepted_at": null }
}

Errors

HTTP	`error`	Endpoint	Meaning
400	`invalid_request`	invite	`name` (2 to 160 characters) or `phone` missing, or `email` malformed; `fields` names them.
400	`invalid_phone`	invite	Not a Saudi mobile. `fields` is `["phone"]`.
409	`owner_already_assigned`	invite	The application already has an owner.
409	`phone_not_eligible`	invite	The phone belongs to one of your users or to another team’s member.
409	`number_connected`	invite, revoke	A WhatsApp number is connected. Disconnect it first.
429	`rate_limited`	invite	Over the invitation caps.
404	`not_found`	all three	Not your `external_id`.

The same handover is available in the partner console, on the application’s Owner card.

Get started

Verify

WhatsApp

Partners

For agents

Application owners

Who does what after a handover

The flow

Read the state

The rules

Take it back

Errors

​Who does what after a handover

​The flow

​Read the state

​The rules

​Take it back

​Errors

Who does what after a handover

The flow

Read the state

The rules

Take it back

Errors