Documentation

SMS Messaging

The guava.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 directly.

sms.py

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

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.

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.

Note the direction: from_number is the external number you're waiting to hear from (the customer), and to_number is your Guava number that receives the reply — the opposite of send_sms.

signature

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 number of seconds to wait before giving up. In TypeScript, pass `timeoutMs` (milliseconds) in the options object; defaults to 60000.
poll_interval	float	2.0	Seconds to wait between inbox checks. In TypeScript, pass `pollIntervalMs` (milliseconds) in the options object; defaults to 2000.

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.

→ Next: Messages API

Questions? hi@goguava.ai

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"])

client.send_sms(
    from_number: str,
    to_number: str,
    message: str,
) -> None

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