Conventions

Base address and paths

All routes start with https://api.impellabs.tech/api/v1/partner/. Every path ends with a slash. A request without the final slash does not work: a GET is redirected and a POST fails. Bodies are JSON, except a file upload, which is multipart form data.

Ids

Id	What it is
`external_ref`	Your own id for a tenant. Plain text with no slash. It cannot be `list`, `.` or `..`. It is the key of every tenant route.
`id` of a tenant	The id of the workspace. UUID.
`phone_number_id`	The WhatsApp number id from Meta. It is the `{pnid}` in a path.
`page_id`	The Facebook Page id from Meta.
Conversation, message, endpoint	UUIDs that ImpelLabs makes.

Tenants are yours only

A tenant of another partner, and a tenant that does not exist, both answer 404. No call tells you which of the two it is.

Paging

Tenant lists use pages. Send page. The answer holds results, page, page_size (100), total and has_more. Conversation lists and message lists use a cursor. Send limit, and after with the next_cursor of the page before. The answer holds has_more and next_cursor. An after that names nothing answers 400. The list of webhook deliveries shows the last 200 and has no paging.

Errors

An error has a 4xx or 5xx status and one of two shapes.

{ "detail": "Tenant not found." }

{ "error": { "code": "outside_customer_service_window", "message": "The 24-hour customer service window is closed. Send an approved template instead." } }

Some errors add code or field beside detail. A validation error names the field that failed. Branch on code when it is present. Do not branch on message.

Status	Meaning
400	The body or a parameter is not valid. Do not repeat it unchanged.
401	The key is missing, wrong, revoked or expired.
403	The scope is missing, the request came from a browser, or your partner account is suspended.
404	The tenant or the item is not yours or does not exist.
409	The request is valid but the state is not ready. Read `code`, for example `human_control`, `number_claimed`, `no_binding`, `no_return_url`, `opted_out`.
422	A channel rule refused it, for example `outside_customer_service_window`, `text_only` or `tag_unsupported`.
502	The channel provider refused the call. Read `error.message`.
503	WhatsApp sign-up is not set up on this server.

Repeating a call

Creating a tenant is safe to repeat: the same external_ref answers 200 with the tenant that exists. Sending the WhatsApp sign-up code is not safe to repeat, because the code works once. Read the channel before you decide.

Time

Times are ISO 8601. They are stored in UTC. Show them in the zone of your viewer.

Get started

Customers

Channels

Events

Partner API reference