Skip to main content

Workspaces

A workspace is one part of your team, such as a branch, an office or a client. It has its own messages, purchases, USSD sessions, contacts, reports and credit. Your team's API keys, Sender IDs and balance stay with the team, and it gives each workspace what it may use.

Ponitor switches workspaces on for your team. Ask us if you need them. Until then, everything you send goes to Main, the workspace every team has, and nothing on this page changes how your requests work. Workspaces are live only: the sandbox ignores them.

Naming a workspace in a request​

Each workspace has a handle, such as gbarnga-branch, set when your team creates it. Add workspace with that handle to any request:

POST /messages
{
  "channel": "SMS",
  "sender": "ACME",
  "recipient": "+231770000000",
  "externalId": "loan-reminder-2201",
  "text": "Your loan payment is due on Friday.",
  "workspace": "gbarnga-branch"
}
  • Body, query or header. Use the workspace body field, a workspace query parameter, or an X-Workspace header. They all mean the same.
  • Leave it out for Main. A request without workspace, or with "workspace": "main", uses Main, as it always has.
  • Reading. A read without workspace, such as GET /messages/{id}, sees your whole team, since your key belongs to it. With workspace, it sees only that workspace, and anything else is 404.
  • externalId stays unique across your whole team, not per workspace.

Credit​

Your team's balance pays for everything. Your team's admins allot part of it to each workspace.

  • A send or purchase in a workspace is charged to that workspace's credit. It never goes below $0.00. When the credit can't cover a charge, Ponitor refuses the request with 400 and doesn't touch your team balance.
  • Main spends what isn't allotted. Your team's overdraft, if you have one, applies to Main only. If Main can't cover a charge, the 400 says how much of the balance is allotted to workspaces. Your team's low-balance alert checks what Main has left.
  • A failed or undelivered message, or a refunded airtime purchase, gives the workspace its credit back.
  • When a workspace's credit drops below $5.00, Ponitor tells its members and your team's admins in the app, its admins by email, and your team's alert contacts by email and SMS.

What a workspace may use​

  • Sender IDs, Short Codes and WhatsApp numbers. Your team requests and connects them, then gives them to workspaces. A workspace sends only from the ones it was given. Several workspaces can share one, such as your bank's Sender ID. A reply goes to the workspace that last messaged that person from that sender, or to Main.
  • USSD codes. A USSD code belongs to one workspace at most. Its sessions, and their charges, go to that workspace.
  • Products. Your team chooses which of SMS, WhatsApp, USSD and airtime each workspace may use. Ponitor refuses a request for a product the workspace doesn't have with 403.

Errors​

StatusWhen
400workspace names a handle your team doesn't have, or the workspace's credit can't cover the charge.
403The workspace is paused or archived, or it wasn't given that product or sender.

The message in the error body says which.

Webhooks​

Your team's webhooks stay one set for the whole team. Every message and airtime event carries the workspace it belongs to, so you can route it on your side:

"workspace": { "id": "2b1e3c4d-5f60-4a71-8b92-a3b4c5d6e7f8", "handle": "gbarnga-branch" }

It is null for Main. See the event reference.

Last updated on