Documentation | Guava

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.

Example Code

Python Code

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

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.

Signature

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

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