Phone numbers

Serverhttps://mqqsoutginqsajeuttyp.supabase.co/functions/v1

Quote, approve, activate, provision and cancel an avatar's exact phone number.

Approve an exact instance quote

POST

https://mqqsoutginqsajeuttyp.supabase.co/functions/v1

/avatar-instance-phone-approve

Binds the caller's unexpired quote to an approved phone intent after a fresh availability check. Never orders a number; when every release switch is on, the intent is queued for activation (activation_queued).

Approve an exact instance quote › Request Body

InstancePhoneApproveRequest

quote_id

Uuid · uuid · required

approved_phone_number

string · pattern: ^\+[1-9][0-9]{7,14}$ · required

Approve an exact instance quote › Responses

Approved; no order placed.

InstancePhoneApproval

approved

boolean · const

Const value:

quote_id

Uuid · uuid

customer_assistant_id

Uuid · uuid

organization_id

Uuid · uuid

phone_number

string

state

string

activation_queued

boolean

order_placed

boolean

POST/avatar-instance-phone-approve

curl https://mqqsoutginqsajeuttyp.supabase.co/functions/v1/avatar-instance-phone-approve \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "quote_id": "00000000-0000-0000-0000-000000000000",
  "approved_phone_number": "approved_phone_number"
}'

Example Request Body

{
  "quote_id": "00000000-0000-0000-0000-000000000000",
  "approved_phone_number": "approved_phone_number"
}

json

Example Responses

{
  "approved": true,
  "quote_id": "00000000-0000-0000-0000-000000000000",
  "customer_assistant_id": "00000000-0000-0000-0000-000000000000",
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "phone_number": "phone_number",
  "state": "state",
  "activation_queued": true,
  "order_placed": false
}

json

application/json

Collect first rent, then order the approved exact number

POST

https://mqqsoutginqsajeuttyp.supabase.co/functions/v1

/avatar-phone-activate

Service-only and default-off. Runs avatar-phone-billing then avatar-phone-provision for one released approval; a failed or action-required payment never buys a number.

Collect first rent, then order the approved exact number › Request Body

ActivateRequest

customer_assistant_id

Uuid · uuid · required

quote_id

Uuid · uuid · required

Collect first rent, then order the approved exact number › Responses

Rent paid and the number is ready.

Activation

rent_paid

boolean · required

state

string · required

order_placed

boolean · required

phone_number

string | null

Approve or dismiss a persona avatar's phone-number request

POST

https://mqqsoutginqsajeuttyp.supabase.co/functions/v1

/avatar-phone-approve

A company admin's click. Approve passes two holds first: the quoted number must still be orderable (409 with a fresh candidate otherwise) and the organization must carry the phone number plan (402 with details.checkout_url for a first buyer). Then the request moves proposed to approved through the caller's RLS client and the order runs as that admin (avatar-phone/approved event).

Approve or dismiss a persona avatar's phone-number request › Request Body

PhoneApproveRequest

requestId

Uuid · uuid · required

action

string · enum · required

Enum values:

approve

cancel

returnPath

string · maxLength: 256

avatarName

string · minLength: 1 · maxLength: 60

Approve or dismiss a persona avatar's phone-number request › Responses

The click was recorded.

requestId

string · uuid · required

approved

boolean · const

Const value:

cancelled

boolean · const

Const value:

Cancel an instance's phone identity and stop routing now

POST

https://mqqsoutginqsajeuttyp.supabase.co/functions/v1

/avatar-phone-cancel

Ends registered calls, then reconciles rent (refund before an order, port-out window after one).

Cancel an instance's phone identity and stop routing now › Request Body

CancelRequest

customer_assistant_id

Uuid · uuid · required

Cancel an instance's phone identity and stop routing now › Responses

Cancelled and settled.

Cancellation

cancelled

boolean · const

Const value:

routing_stopped

boolean · const

Const value:

registered_calls_ended

boolean

registered_calls_pending

integer

rent_reconciliation

string · enum

Enum values:

none

portout

cancelled_uncharged

refunded

pending

phone_number

string | null

port_out_deadline

string | null · date-time

release_after

string | null · date-time

Order and route a paid, released exact number

POST

https://mqqsoutginqsajeuttyp.supabase.co/functions/v1

/avatar-phone-provision

Service-only and default-off (INSTANCE_PHONE_ORDER_ENABLED). Never searches for a replacement: it orders the one approved E.164 number, then reconciles SMS compliance, the SMS route, the voice route and the LiveKit dispatch.

Order and route a paid, released exact number › Request Body

ProvisionRequest

customer_assistant_id

Uuid · uuid · required

Order and route a paid, released exact number › Responses

Ready.

Provisioning

phone_number

string | null

state

string

order_placed

boolean

voice_connection_ready

boolean

voice_route_ready

boolean

sms_profile_ready

boolean

sms_compliance_ready

boolean

sms_route_ready

boolean

active

boolean

Quote one exact, currently available phone number

POST

https://mqqsoutginqsajeuttyp.supabase.co/functions/v1

/avatar-phone-quote

Search only, never a purchase. Two callers share the function: an owner or company admin with their own JWT quoting for one avatar instance (InstanceQuoteRequest), or the avatar worker's service-role JWT quoting the number a persona avatar's recorded request will show (PersonaQuoteRequest, chosen when the body has request_id and no customer_assistant_id). A quote expires after 5 minutes.

Quote one exact, currently available phone number › Request Body

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object · requires: customer_assistant_id
	type = object · requires: request_id

Properties for Variant 1:

InstanceQuoteRequest

customer_assistant_id

Uuid · uuid · required

area_code

string | null · pattern: ^[2-9][0-9]{2}$

phone_number

string | null · pattern: ^\+1[2-9][0-9]{9}$

An exact number to re-check instead of searching.

Quote one exact, currently available phone number › Responses

The quoted number and its price.

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for Variant 1:

InstanceQuote

quote_id

Uuid · uuid

customer_assistant_id

Uuid · uuid

organization_id

Uuid · uuid

phone_number

string

preferred_area_code_matched

boolean

requested_area_code

string | null

expires_at

string · date-time

area_code_unavailable

boolean

availability_message

string

object

requires_exact_number_approval

boolean · const

Const value:

POST/avatar-phone-quote

curl https://mqqsoutginqsajeuttyp.supabase.co/functions/v1/avatar-phone-quote \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "customer_assistant_id": "00000000-0000-0000-0000-000000000000",
  "area_code": "area_code",
  "phone_number": "phone_number"
}'

Example Request Body

{
  "customer_assistant_id": "00000000-0000-0000-0000-000000000000",
  "area_code": "area_code",
  "phone_number": "phone_number"
}

json

Example Responses

{
  "quote_id": "00000000-0000-0000-0000-000000000000",
  "customer_assistant_id": "00000000-0000-0000-0000-000000000000",
  "organization_id": "00000000-0000-0000-0000-000000000000",
  "phone_number": "phone_number",
  "preferred_area_code_matched": true,
  "requested_area_code": "requested_area_code",
  "expires_at": "2024-08-25T15:00:00Z",
  "area_code_unavailable": true,
  "availability_message": "availability_message",
  "pricing": {
    "platform_monthly_usd": "platform_monthly_usd",
    "phone_monthly_usd": "phone_monthly_usd",
    "ai_voice_per_minute_usd": "ai_voice_per_minute_usd",
    "sms_per_segment_usd": "sms_per_segment_usd"
  },
  "requires_exact_number_approval": true
}

json

application/json

Inbound events