## SMS Messaging

The [`guava.Client`](https://goguava.ai/docs/client) can send SMS messages from your Guava numbers and wait for inbound replies. This is useful for sending confirmations and reminders, or for collecting a response between calls.

SMS messaging is available in the **Python and TypeScript SDKs**. For other languages, call the equivalent [Messages REST API](https://goguava.ai/docs/messages-api) directly.

### Example Code

#### Python Code
```python
import guava
import os

client = guava.Client(api_key=os.environ["GUAVA_API_KEY"])

agent_number = os.environ["GUAVA_AGENT_NUMBER"]   # one of your Guava numbers
customer = "+15551234567"

# Send an SMS from your Guava number to the customer.
client.send_sms(
    from_number=agent_number,
    to_number=customer,
    message="Hi! Reply YES to confirm your appointment, or STOP to opt out.",
)

# Block until the customer replies, giving up after 5 minutes.
reply = client.next_sms(from_number=customer, to_number=agent_number, timeout=300)

if reply is None:
    print("No reply within 5 minutes.")
else:
    print("Customer replied:", reply["content"])
```

### send_sms / sendSms

Send a single SMS message. The `from_number` must be one of your Guava numbers with SMS configured, and the message is delivered to `to_number`.

#### Signature
```python
client.send_sms(
    from_number: str,
    to_number: str,
    message: str,
) -> None
```

| Parameter      | Type | Default | Description                                                                 |
|----------------|------|---------|-----------------------------------------------------------------------------|
| from_number    | str  | —       | One of your Guava numbers, in E.164 format (e.g. "+15551230001"). Must have SMS enabled. |
| to_number      | str  | —       | The recipient's number, in E.164 format.                                   |
| message        | str  | —       | The message body to send.                                                  |

Returns nothing (Python `None`; TypeScript resolves `void`). Raises (Python) / rejects (TypeScript) if the `from_number` isn't owned by your organization or doesn't have SMS configured.

Sending SMS requires your organization to complete SMS brand and campaign registration. See [Outbound & SMS Permissions](https://goguava.ai/docs/outbound-and-sms-permissions).

### next_sms / nextSms

Wait for the next inbound SMS sent **to** one of your Guava numbers **from** a given number, and return it. `next_sms` polls your inbox and only returns messages received after the call begins, so a reply to an earlier message won't be returned twice.

#### Signature
```python
client.next_sms(
    from_number: str,
    to_number: str,
    *,
    timeout: float = 60.0,
    poll_interval: float = 2.0,
) -> dict | None
```

| Parameter      | Type   | Default | Description                                                                |
|----------------|--------|---------|----------------------------------------------------------------------------|
| from_number    | str    | —       | The external number you're waiting to hear from, in E.164 format.         |
| to_number      | str    | —       | Your Guava number that will receive the reply, in E.164 format.           |
| timeout         | float  | 60.0    | Maximum seconds to wait before giving up.                                  |
| poll_interval   | float  | 2.0     | Seconds to wait between inbox checks.                                       |

Returns the message (Python `dict` / TypeScript `SmsMessage`), or `None` / `null` if the timeout elapses with no new message. A message has the following fields:

| Parameter      | Type | Default | Description                                   |
|----------------|------|---------|-----------------------------------------------|
| id             | str  | —       | Unique ID of the message.                    |
| from_number    | str  | —       | The number that sent the message.           |
| to_number      | str  | —       | Your Guava number that received the message. |
| content        | str  | —       | The message body.                           |
| received_at    | str  | —       | When the message was received, in ISO 8601 format. |
| modality       | str  | —       | The channel the message arrived on. Currently always "sms". |
| direction      | str  | —       | Always "inbound" for received messages.