Conversations API

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://app.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://app.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

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

Example

curl -H 'Authorization: Bearer YOUR_GUAVA_API_KEY' \
  https://app.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

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

Example

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

Get conversation channel recording

GET /v1/conversations/{call_id}/channels/{channel_name}/recording

Download the audio recording for a single side of a conversation in WAV format. This is useful when you want to analyze or store each speaker’s audio separately.

Parameters

Name	Type	Required	Description
`call_id`	string	Yes	ID of the call
`channel_name`	string	Yes	Which channel to download: `"agent"` (your agent’s audio), `"remote"` (the other party on the call, whether the call was inbound or outbound), or `"mixed"` (both sides combined, same as Get conversation recording).

Response

WAV audio file.

Errors

Status	Description
401	Invalid authentication
404	The call with this ID does not exist, or no recording is available for this channel
422	`channel_name` is not one of `"agent"`, `"remote"`, or `"mixed"`

Example

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

Overview

API Reference

SMS

List conversations

Parameters

Response

Errors

Example

Get conversation details

Parameters

Response

Errors

Example

Get conversation transcript

Parameters

Response

Errors

Example

Get conversation recording

Parameters

Response

Errors

Example

Get conversation channel recording

Parameters

Response

Errors

Example

​List conversations

​Parameters

​Response

​Pagination

​Errors

​Example

​Get conversation details

​Parameters

​Response

​Errors

​Example

​Get conversation transcript

​Parameters

​Response

​Errors

​Example

​Get conversation recording

​Parameters

​Response

​Errors

​Example

​Get conversation channel recording

​Parameters

​Response

​Errors

​Example

List conversations

Parameters

Response

Pagination

Errors

Example

Get conversation details

Parameters

Response

Errors

Example

Get conversation transcript

Parameters

Response

Errors

Example

Get conversation recording

Parameters

Response

Errors

Example

Get conversation channel recording

Parameters

Response

Errors

Example