messaging.md

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.

Examples

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

import * as guava from "@guava-ai/guava-sdk";

const client = new guava.Client(process.env.GUAVA_API_KEY);

const agentNumber = process.env.GUAVA_AGENT_NUMBER;  // one of your Guava numbers
const customer = "+15551234567";

// Send an SMS from your Guava number to the customer.
await client.sendSms(
  agentNumber,
  customer,
  "Hi! Reply YES to confirm your appointment, or STOP to opt out.",
);

// Block until the customer replies, giving up after 5 minutes.
const reply = await client.nextSms(customer, agentNumber, { timeoutMs: 300_000 });

if (reply === null) {
  console.log("No reply within 5 minutes.");
} else {
  console.log("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.

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

await client.sendSms(
  fromNumber: string,
  toNumber: string,
  message: string,
): Promise<void>

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.

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.

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

await client.nextSms(
  fromNumber: string,
  toNumber: string,
  options?: { timeoutMs?: number; pollIntervalMs?: number },
): Promise<SmsMessage | null>

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