Documentation | Guava

Conversations

These endpoints let you retrieve, inspect, and delete conversation data for completed calls.

All requests require an Authorization: Bearer YOUR_GUAVA_API_KEY header. See the API Overview for details.

List conversations

GET /v1/conversations

List your organization's conversations, newest first. Use the filters below to narrow results — for example, to pull every call to or from a given phone number, with each call's duration, to build a usage or billing report.

Parameters

Name Type Required Description
from_number string No Only return calls placed from this number. E.164 format (e.g. +15551234567).
to_number string No Only return calls placed to this number. E.164 format.
direction string No Only return calls in this direction: "inbound" or "outbound" (from the perspective of your agent). Use "all" or omit for both.
date_from string No Only return calls at or after this time (ISO 8601, e.g. 2026-06-01T00:00:00Z).
date_to string No Only return calls at or before this time (ISO 8601).
campaign_id string No Only return calls placed by this outbound campaign.
limit integer No Maximum number of conversations to return, between 1 and 100. Defaults to 50.
after string No Pagination cursor. Pass the next_cursor from the previous response to fetch the next page.

Response

A JSON object with the following fields:

Field Type Description
conversations array The matching conversations, newest first. Each is the same object returned by Get conversation details.
next_cursor string (nullable) Pass as after to fetch the next page. null when there are no more results.
has_more boolean true if more conversations match than were returned in this response.

Each conversation includes the call's duration_sec, so you can total call time without fetching each conversation individually.

Pagination

Conversations are returned newest first. When has_more is true, request the next page by calling again with after set to the next_cursor from the previous response. Keep paging until has_more is false to retrieve the full set.

Errors

Status Description
400 Invalid limit, after cursor, campaign_id, or date value
401 Invalid authentication
422 from_number or to_number is not a valid E.164 number

Example

curl -G https://api.goguava.ai/v1/conversations \
  -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  --data-urlencode 'from_number=+15551234567' \
  --data-urlencode 'date_from=2026-06-01T00:00:00Z'

Sample response:

{
  "conversations": [\
    {\
      "id": "6064ab9663dc4eb0",\
      "call_id": "6064ab9663dc4eb0",\
      "ts": "2026-06-09T00:12:04.518000+00:00",\
      "direction": "outbound",\
      "from_number": "+15551234567",\
      "to_number": "+15551230001",\
      "duration_sec": 142,\
      "campaign_id": null,\
      "termination_reason": "user-hangup"\
    }\
  ],
  "next_cursor": null,
  "has_more": false
}

The + in a phone number must be URL-encoded as %2B in query strings. The curl -G --data-urlencode form above handles this for you.

Get conversation details

GET /v1/conversations/{call_id}

Retrieve metadata about a single conversation.

Parameters

Name Type Required Description
call_id string Yes ID of the call

Response

A JSON object with the following fields:

Field Type Description
id string Unique ID of the conversation
call_id string ID of the call
ts string Date of the call in ISO 8601 format
direction string "inbound" or "outbound" (from the perspective of your agent)
from_number string Phone number that initiated the call
to_number string Phone number that received the call
duration_sec integer (nullable) How long the call lasted in seconds. null until the call completes.
campaign_id string (nullable) Outbound campaign that initiated this call, if applicable
termination_reason string (nullable) How the call ended (e.g. "user-hangup"), if known

Errors

Status Description
401 Invalid authentication
404 The call with this ID does not exist

Example

curl -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  https://api.goguava.ai/v1/conversations/6064ab9663dc4eb0

Get conversation transcript

GET /v1/conversations/{call_id}/transcript

Download the transcript for a conversation as a list of turns.

Parameters

Name Type Required Description
call_id string Yes ID of the call

Response

A JSON array of turn objects. Each turn has:

Field Type Description
speaker string "HUMAN" or "AGENT"
text string What was said by the speaker
offset_ms integer Milliseconds into the call when this turn began

Errors

Example

curl -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  https://api.goguava.ai/v1/conversations/6064ab9663dc4eb0/transcript

Get conversation recording

GET /v1/conversations/{call_id}/recording

Download the audio recording for a conversation in WAV format.

Parameters

Name Type Required Description
call_id string Yes ID of the call

Response

WAV audio file.

Errors

Example

curl -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  -o recording.wav \
  https://api.goguava.ai/v1/conversations/6064ab9663dc4eb0/recording

Delete a conversation

DELETE /v1/conversations/{call_id}

Permanently delete a conversation and its associated data.

Parameters

Name Type Required Description
call_id string Yes ID of the call

Response

None (empty body).

Errors

Example

curl -X DELETE -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  https://api.goguava.ai/v1/conversations/6064ab9663dc4eb0