Send a text message from a number
Send a text message from one of the workspace's phone numbers (its id from list_phone_numbers) to up to 5 mobile numbers in international form, e.g. +61412345678. Use it to alert your team from your own systems, for example when a website form comes in. The sending number must be able to text: in Australia that is a mobile number (04xx), never a landline. Each text is billed as SMS usage, a workspace can send at most 30 an hour this way, and a message longer than one text is sent in parts. Returns each text sent with its message id, and each number it could not reach with the reason. Needs owner or admin.
Authorization
bearerAuth A personal access token from Settings > API tokens.
In: header
Path Parameters
Workspace slug (GET /me lists yours).
Header Parameters
A key you choose, such as a UUID, that makes this POST safe to retry. Within 24 hours the same key and request answers with the first successful answer and runs nothing, the same key with a different request answers 422 idempotency_key_reused, and a key whose request is still running answers 409 idempotency_key_in_use. A failed request keeps nothing, so the same key runs it again.
1 <= length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://example.com/workspaces/string/phone-numbers/string/messages" \ -H "Content-Type: application/json" \ -d '{ "to": [ "string" ], "text": "string" }'{
"from": "string",
"sent": [
{
"to": "string",
"messageId": "string",
"parts": 0,
"property1": null,
"property2": null
}
],
"failed": [
{
"to": "string",
"error": "string",
"property1": null,
"property2": null
}
],
"property1": null,
"property2": null
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"code": "string",
"errors": [
{
"path": "string",
"message": "string"
}
],
"estimate": {},
"retryAfterSeconds": 0
}Remove a phone number DELETE
Remove a phone number from a workspace: stop its Stripe rental billing, unassign it from any agent, and drop the workspace's claim. This does NOT release the number to the provider. It stays owned by Vertical AI and deletion-locked, so support can hand it back to this workspace or another one later. Same retain-don't-release path as the Remove button on the workspace's Phone numbers page. Releasing a number to the provider's public pool has no MCP tool on purpose; that stays a human action in the app. Use this too to clear a workspace row whose number no longer exists at the carrier (reconcile_phone_numbers reports those). Destructive: pass confirm: true.
Stop routing a number POST
Detach a phone number from the agent it routes to, keeping the number in the workspace. Calls stop reaching that agent. The number stays in list_phone_numbers; point it at another agent with assign_phone_number, or drop it from the workspace with remove_phone_number. Its inventory labels at the carrier still read status_live afterwards, so run sync_phone_number_labels to re-stamp them as spare.