Partners

For a business that serves its own clients: a platform, an agency or a software company. Each of your clients links its own WhatsApp number from inside your product, and you manage them all through the API. Partner access is by agreement: write to us to become a partner.

How it works#

Each client is an account of its own under yours. It has its own instances, API keys, webhook, chats and contacts. One client never sees another's data, and each client's numbers keep their own pace and protection.

What a client shares with you:

• Your plan's instances. Your plan's instances cover yours and all your clients', together.
• Your plan's allowances, if it has any (messages a day and the like): one count for you and all your clients.
• Your features. A client has the features your plan has.
• Your account's state. While your account is suspended, your clients are too, and they start again with it.
• Your bill. You pay for your clients' numbers, as below.
• Your team's emails. A client has no people of its own. Notices about its instances go to your team, with the client's name first.

Add a client and link its number#

1. Add the client: POST /v1/clients with a name. The answer has its id.
2. Make it a key: POST /v1/clients/{id}/keys with a name. The answer holds the key in data.token, once: store it, it is not shown again.
3. Use the client's key for everything else: with it, POST /v1/instances adds an instance for that client. Then show GET /v1/instances/{id}/qr in your product, as in Linking an instance.
4. Hear from it: set the client's webhook with its key, PATCH /v1/webhook, as in Webhooks and events. Each client may have its own address, or all of them yours.

curl -X POST https://threadwire.net/api/v1/clients \
  -H "Authorization: Bearer YOUR_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Cairo Bakery"}'

Show the QR code in your own product#

Your client links its number on your screens, never on ours:

• GET /v1/instances/{id}/qr answers data.image, a picture to put in an <img src> as it is, and data.value, the text to draw it with any QR library. The code changes: fetch it again every few seconds until the instance is linked.
• Or POST /v1/instances/{id}/pairing-code with the phone's number as phone: your client types the code in WhatsApp → Linked devices → Link with phone number instead.
• You hear it linked by the instance.status webhook, or see status become working in GET /v1/instances/{id}. Give the instance your own external_ref when you add it, and find it again with GET /v1/instances?external_ref=….
• On the phone, WhatsApp → Linked devices lists the link under the name Threadwire.

The rest is in Linking an instance: what each answer means while linking, and how to restart, stop, unlink or remove an instance.

The client's keys#

• access is full (the default), send (send and read) or read.
• With instance_id, the key works only on that instance of the client.
• GET /v1/clients/{id}/keys lists its keys by name and access, never the keys themselves.
• DELETE /v1/clients/{id}/keys/{key} revokes one at once.

A client may hold up to 10 keys.

Manage your clients#

• GET /v1/clients lists them, newest first, each with its status (active or suspended) and how many instances it has.
• GET /v1/clients/{id} shows one. PATCH /v1/clients/{id} renames it.
• DELETE /v1/clients/{id} removes a client with its keys and history, for good. It answers 409 while the client has instances: remove those first with its key, DELETE /v1/instances/{id}.

Your bill#

You pay each month, after it ends, for every number you and your clients had linked on at least one day of it. On the 1st we email your admins the bill: how many numbers, the price of each and the total. Your panel's Billing page shows this month's numbers so far, your bills, and how to pay. Pay by the date on the bill, then press I've paid a bill there with the transfer's reference.

An unpaid bill pauses the API and sending for you and your clients some days after its due date; webhook events are kept. Your instances stay linked, and everything starts again once your payment reaches us. Clients in your panel lists your clients, each with its instances and its numbers this month.

Who may#

Only a partner's account key that may manage. A send-only or read-only key, an instance key and a client's own key answer 403. An account that is not a partner gets 403 with feature_not_included.