> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nonhumans.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone API — SMS Messaging, Voice Calls & Inbound Logs

> REST API reference for the Nonhumans Phone primitive — send SMS, make voice calls, and list inbound messages from your agent's number.

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.

```bash theme={null}
curl https://api.nonhumans.ai/v1/phone \
  -H "Authorization: Bearer $NONHUMANS_KEY"
```

**Example response:**

```json theme={null}
{
  "number": "+14155550192",
  "country": "US",
  "capabilities": {
    "sms": true,
    "voice": true
  }
}
```

<ResponseField name="number" type="string">
  The agent's phone number in E.164 format (e.g. `+14155550192`).
</ResponseField>

<ResponseField name="country" type="string">
  ISO 3166-1 alpha-2 country code of the number's origin (e.g. `US`, `GB`).
</ResponseField>

<ResponseField name="capabilities" type="object">
  Object describing what the number supports.

  <Expandable title="Capability fields">
    <ResponseField name="sms" type="boolean">
      Whether the number can send and receive SMS messages.
    </ResponseField>

    <ResponseField name="voice" type="boolean">
      Whether the number can make and receive voice calls.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## POST /v1/phone/sms

Send an SMS message from your agent's number to any E.164-formatted phone number.

```bash theme={null}
curl -X POST https://api.nonhumans.ai/v1/phone/sms \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+12025550147",
    "message": "Hi! Your order has been confirmed. Reply STOP to unsubscribe."
  }'
```

<ParamField body="to" type="string" required>
  Recipient phone number in E.164 format (e.g. `+12025550147`).
</ParamField>

<ParamField body="message" type="string" required>
  The text content of the SMS. Messages over 160 characters are automatically segmented into multiple parts.
</ParamField>

**Example response:**

```json theme={null}
{
  "message_id": "sms_01HXYZ456",
  "status": "queued"
}
```

<ResponseField name="message_id" type="string">
  Unique identifier for the SMS message. Use this to track delivery status.
</ResponseField>

<ResponseField name="status" type="string">
  Initial delivery status. One of `queued`, `sent`, `delivered`, or `failed`.
</ResponseField>

<Note>
  Delivery status transitions from `queued` → `sent` → `delivered` asynchronously. Poll the message status or configure a webhook to receive real-time delivery updates.
</Note>

***

## GET /v1/phone/messages

List inbound SMS messages received by your agent's number. Messages are returned in reverse chronological order.

```bash theme={null}
curl "https://api.nonhumans.ai/v1/phone/messages?limit=20" \
  -H "Authorization: Bearer $NONHUMANS_KEY"
```

<ParamField query="limit" type="integer">
  Number of messages to return. Default `20`, max `100`.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response's `next_cursor`.
</ParamField>

<ParamField query="since" type="string (ISO 8601)">
  Only return messages received after this timestamp.
</ParamField>

**Example response:**

```json theme={null}
{
  "messages": [
    {
      "id": "sms_01HINB001",
      "from": "+12025550147",
      "to": "+14155550192",
      "body": "Thanks for the update!",
      "received_at": "2024-12-01T16:22:00Z"
    }
  ],
  "next_cursor": null
}
```

<ResponseField name="messages" type="array">
  Array of inbound SMS message objects.

  <Expandable title="Message fields">
    <ResponseField name="id" type="string">
      Unique message identifier.
    </ResponseField>

    <ResponseField name="from" type="string">
      Sender's phone number in E.164 format.
    </ResponseField>

    <ResponseField name="to" type="string">
      Your agent's phone number.
    </ResponseField>

    <ResponseField name="body" type="string">
      Full text content of the received SMS.
    </ResponseField>

    <ResponseField name="received_at" type="string (ISO 8601)">
      Timestamp when the message was received.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## 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.

```bash theme={null}
curl -X POST https://api.nonhumans.ai/v1/phone/calls \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+12025550147",
    "script": "Hello! This is a reminder that your appointment is tomorrow at 2pm. Press 1 to confirm."
  }'
```

<ParamField body="to" type="string" required>
  The phone number to call, in E.164 format.
</ParamField>

<ParamField body="script" type="string">
  Text-to-speech script the agent will speak when the call connects. Either `script` or `twiml_url` is required.
</ParamField>

<ParamField body="twiml_url" type="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.
</ParamField>

**Example response:**

```json theme={null}
{
  "call_id": "call_01HXYZ789",
  "status": "initiated"
}
```

<ResponseField name="call_id" type="string">
  Unique identifier for the voice call. Use this to track call progress.
</ResponseField>

<ResponseField name="status" type="string">
  Initial call status. One of `initiated`, `ringing`, `in-progress`, `completed`, or `failed`.
</ResponseField>

<Warning>
  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.
</Warning>