Skip to main content
Every Nonhumans agent is provisioned a real phone number capable of sending and receiving SMS and initiating voice calls. The Phone API lets your agent interact with humans and services over the PSTN — useful for notifications, two-factor authentication flows, outbound outreach, and voice-driven automation. No telephony setup required.

​
GET /v1/phone

Returns the phone number assigned to your agent, along with its country and supported capabilities.
Example response:
​
number
string
The agent’s phone number in E.164 format (e.g. +14155550192).
​
country
string
ISO 3166-1 alpha-2 country code of the number’s origin (e.g. US, GB).
​
capabilities
object
Object describing what the number supports.

​
POST /v1/phone/sms

Send an SMS message from your agent’s number to any E.164-formatted phone number.
​
to
string
required
Recipient phone number in E.164 format (e.g. +12025550147).
​
message
string
required
The text content of the SMS. Messages over 160 characters are automatically segmented into multiple parts.
Example response:
​
message_id
string
Unique identifier for the SMS message. Use this to track delivery status.
​
status
string
Initial delivery status. One of queued, sent, delivered, or failed.
Delivery status transitions from queued → sent → delivered asynchronously. Poll the message status or configure a webhook to receive real-time delivery updates.

​
GET /v1/phone/messages

List inbound SMS messages received by your agent’s number. Messages are returned in reverse chronological order.
​
limit
integer
Number of messages to return. Default 20, max 100.
​
cursor
string
Pagination cursor from a previous response’s next_cursor.
​
since
string (ISO 8601)
Only return messages received after this timestamp.
Example response:
​
messages
array
Array of inbound SMS message objects.

​
POST /v1/phone/calls

Initiate an outbound voice call from your agent’s number. You can provide a script for text-to-speech or a URL pointing to a TwiML document for programmatic call flow control.
​
to
string
required
The phone number to call, in E.164 format.
​
script
string
Text-to-speech script the agent will speak when the call connects. Either script or twiml_url is required.
​
twiml_url
string
URL of a TwiML document to drive the call flow. Use this for interactive calls, recordings, or branching logic. Either script or twiml_url is required.
Example response:
​
call_id
string
Unique identifier for the voice call. Use this to track call progress.
​
status
string
Initial call status. One of initiated, ringing, in-progress, completed, or failed.
Calls to certain regions may require regulatory compliance (e.g. caller ID registration or DNC list checks). Ensure your use case complies with local telecommunications laws before initiating outbound calls.