Guava.Client (Guava v0.34.0)

Copy Markdown View Source

Account-level client for Guava's HTTP API.

Handles authentication, phone numbers, SMS, outbound-call creation, and agent-code provisioning. Realtime call handling is done via Guava.Agent.

Authentication

# Explicit key
client = Guava.Client.new(api_key: "gva-...")

# From the GUAVA_API_KEY env var, a deploy token, or a CLI session
{:ok, client} = Guava.Client.new()

Summary

Types

result(x)
t()

Functions

check_sdk_deprecation(client)

Check whether this SDK version is deprecated. Returns the server's deprecation_status string (e.g. "supported").

check_sdk_deprecation!(client)
create_outbound(client, from_number, to_number)

Low-level helper: create an outbound call and return its call_id without attaching an agent. Most code should instead place the call and run an agent on it in one step, with Guava.run/1 and a Guava.Channel outbound listener

create_outbound!(client, from_number, to_number)
create_sip_agent(client)

Create a SIP agent code.

create_sip_agent!(client)
create_webrtc_agent(client, ttl_seconds \\ nil)

Create a WebRTC agent code for browser connectivity. ttl_seconds optionally sets an expiry.

create_webrtc_agent!(client, ttl_seconds \\ nil)
http_url(client, path)

Return the resolved HTTP base URL for path.

list_numbers(client)

List the phone numbers on your account.

list_numbers!(client)
new(opts \\ [])

Build a client, returning {:ok, client} | {:error, %Guava.Error{}}.

new!(opts \\ [])

Like new/1, but raises Guava.Error when credentials can't be resolved.

next_sms(client, from_number, to_number, opts \\ [])

Wait for and return the next inbound SMS from from_number to to_number.

next_sms!(client, from_number, to_number, opts \\ [])
send_sms(client, from_number, to_number, message)

Send an outbound SMS.

send_sms!(client, from_number, to_number, message)
websocket_url(client, path)

Return the resolved WebSocket URL for path.

Types

result(x)

@type result(x) :: {:ok, x} | {:error, Guava.Error.t()}

t()

@type t() :: %Guava.Client{
  auth: Guava.Auth.t(),
  base_url: String.t(),
  req_options: keyword()
}

Functions

check_sdk_deprecation(client)

@spec check_sdk_deprecation(t()) :: result(String.t())

Check whether this SDK version is deprecated. Returns the server's deprecation_status string (e.g. "supported").

check_sdk_deprecation!(client)

@spec check_sdk_deprecation!(t()) :: String.t()

create_outbound(client, from_number, to_number)

@spec create_outbound(t(), String.t(), String.t()) :: result(String.t())

Low-level helper: create an outbound call and return its call_id without attaching an agent. Most code should instead place the call and run an agent on it in one step, with Guava.run/1 and a Guava.Channel outbound listener:

Guava.run({Guava.Channel, agent: MyAgent, outbound: {from, to, %{}}})

create_outbound!(client, from_number, to_number)

@spec create_outbound!(t(), String.t(), String.t()) :: String.t()

create_sip_agent(client)

@spec create_sip_agent(t()) :: result(String.t())

Create a SIP agent code.

create_sip_agent!(client)

@spec create_sip_agent!(t()) :: String.t()

create_webrtc_agent(client, ttl_seconds \\ nil)

@spec create_webrtc_agent(t(), pos_integer() | nil) :: result(String.t())

Create a WebRTC agent code for browser connectivity. ttl_seconds optionally sets an expiry.

create_webrtc_agent!(client, ttl_seconds \\ nil)

@spec create_webrtc_agent!(t(), pos_integer() | nil) :: String.t()

http_url(client, path)

@spec http_url(t(), String.t()) :: String.t()

Return the resolved HTTP base URL for path.

list_numbers(client)

@spec list_numbers(t()) :: result([Guava.PhoneNumberInfo.t()])

List the phone numbers on your account.

list_numbers!(client)

@spec list_numbers!(t()) :: [Guava.PhoneNumberInfo.t()]

new(opts \\ [])

@spec new(keyword()) :: result(t())

Build a client, returning {:ok, client} | {:error, %Guava.Error{}}.

Options

  • :api_key — explicit API key. Falls back to config :guava, api_key:, the deploy token file, the GUAVA_API_KEY env var, then a CLI session.
  • :base_url — override the API base URL.
  • :req_options — extra Req options merged into every request (mainly for testing, e.g. plug:).

new!(opts \\ [])

@spec new!(keyword()) :: t()

Like new/1, but raises Guava.Error when credentials can't be resolved.

next_sms(client, from_number, to_number, opts \\ [])

@spec next_sms(t(), String.t(), String.t(), keyword()) :: result(map() | nil)

Wait for and return the next inbound SMS from from_number to to_number.

Polls the inbox for messages received after this call begins, blocking until one arrives or :timeout elapses. Returns {:ok, message | nil} (nil on timeout) or {:error, %Guava.Error{}}.

Options

  • :timeout — max seconds to wait (default 60.0).
  • :poll_interval — seconds between polls (default 2.0).

next_sms!(client, from_number, to_number, opts \\ [])

@spec next_sms!(t(), String.t(), String.t(), keyword()) :: map() | nil

send_sms(client, from_number, to_number, message)

@spec send_sms(t(), String.t(), String.t(), String.t()) :: result(:ok)

Send an outbound SMS.

send_sms!(client, from_number, to_number, message)

@spec send_sms!(t(), String.t(), String.t(), String.t()) :: :ok

websocket_url(client, path)

@spec websocket_url(t(), String.t()) :: String.t()

Return the resolved WebSocket URL for path.