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

NameTypeRequiredDescription
from_numberstringNoOnly return calls placed from this number. E.164 format (e.g. +15551234567).
to_numberstringNoOnly return calls placed to this number. E.164 format.
directionstringNoOnly return calls in this direction: "inbound" or "outbound" (from the perspective of your agent). Use "all" or omit for both.
date_fromstringNoOnly return calls at or after this time (ISO 8601, e.g. 2026-06-01T00:00:00Z).
date_tostringNoOnly return calls at or before this time (ISO 8601).
campaign_idstringNoOnly return calls placed by this outbound campaign.
limitintegerNoMaximum number of conversations to return, between 1 and 100. Defaults to 50.
afterstringNoPagination cursor. Pass the next_cursor from the previous response to fetch the next page.

Response

A JSON object with the following fields:

FieldTypeDescription
conversationsarrayThe matching conversations, newest first. Each is the same object returned by Get conversation details.
next_cursorstring (nullable)Pass as after to fetch the next page. null when there are no more results.
has_morebooleantrue 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

StatusDescription
400Invalid limit, after cursor, campaign_id, or date value
401Invalid authentication
422from_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

NameTypeRequiredDescription
call_idstringYesID of the call

Response

A JSON object with the following fields:

FieldTypeDescription
idstringUnique ID of the conversation
call_idstringID of the call
tsstringDate of the call in ISO 8601 format
directionstring"inbound" or "outbound" (from the perspective of your agent)
from_numberstringPhone number that initiated the call
to_numberstringPhone number that received the call
duration_secinteger (nullable)How long the call lasted in seconds. null until the call completes.
campaign_idstring (nullable)Outbound campaign that initiated this call, if applicable
termination_reasonstring (nullable)How the call ended (e.g. "user-hangup"), if known

Errors

StatusDescription
401Invalid authentication
404The 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

NameTypeRequiredDescription
call_idstringYesID of the call

Response

A JSON array of turn objects. Each turn has:

FieldTypeDescription
speakerstring"HUMAN" or "AGENT"
textstringWhat was said by the speaker
offset_msintegerMilliseconds into the call when this turn began

Errors

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

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

NameTypeRequiredDescription
call_idstringYesID of the call

Response

WAV audio file.

Errors

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

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

NameTypeRequiredDescription
call_idstringYesID of the call

Response

None (empty body).

Errors

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

Example

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

Questions? hi@goguava.ai