Guides

List Calls

Suggest Edits

List Calls

The Flyflow API allows you to retrieve a list of calls associated with your account by making a GET request to the /calls endpoint. This endpoint returns paginated results, allowing you to specify the number of calls to retrieve and navigate through the call history.

Request

Endpoint

GET /calls

Headers

  • Authorization: The API key prefixed with Bearer. Example: Bearer your_api_key.

Query Parameters

  • cursor (string, optional): The cursor value to start the list from. This value is returned in the response of the previous request and allows for pagination.
  • limit (integer, optional): The maximum number of calls to return in the response. The default value is 10, and the maximum allowed value is 100.
  • agent_id (string, optional): The identifier of the agent to filter the calls by. If provided, only calls associated with the specified agent will be returned.
  • client_number (string, optional): The phone number of the client to filter the calls by. If provided, only calls associated with the specified client number will be returned.

cURL Example

curl -X GET \
  -H "Authorization: Bearer your_api_key" \
  "https://api.flyflow.dev/v1/calls?limit=20&agent_id=agent_id&client_number=+1234567890"

Replace agent_id with the actual ID of the agent and +1234567890 with the actual client phone number to filter the calls by (if desired).

Python Client Example

from flyflowclient import Flyflow

client = Flyflow(api_key='your_api_key')

calls = client.list_calls(limit=20, agent_id='agent_id', client_number='+1234567890')

for call in calls['calls']:
    print(call)

Replace agent_id with the actual ID of the agent and +1234567890 with the actual client phone number to filter the calls by (if desired).

Response

Status Codes

  • 200 OK: The list of calls was successfully retrieved.
  • 401 Unauthorized: The API key is missing or invalid.
  • 500 Internal Server Error: An unexpected error occurred on the server side.

Response Body

If the list of calls is successfully retrieved, the response body will be a JSON object containing the paginated call results:

{
  "num_items": 20,
  "cursor": "next_cursor_value",
  "calls": [
    {
      "id": "call_id_1",
      "agent_id": "agent_id",
      "client_number": "+1234567890",
      "context": "Call context 1",
      "status": "completed",
      "created_at": "timestamp"
    },
    {
      "id": "call_id_2",
      "agent_id": "agent_id",
      "client_number": "+5555555555",
      "context": "Call context 2",
      "status": "in_progress",
      "created_at": "timestamp"
    },
    ...
  ]
}
  • num_items (integer): The total number of calls returned in the response.
  • cursor (string): The cursor value to use for retrieving the next page of results (if applicable).
  • calls (array): An array of call objects representing the retrieved calls.
    • id (string): The unique identifier of the call.
    • agent_id (string): The identifier of the agent associated with the call.
    • client_number (string): The phone number of the client associated with the call.
    • context (string): The context or message associated with the call.
    • status (string): The current status of the call (e.g., "completed", "in_progress").
    • created_at (string): The timestamp indicating when the call was created.

Error Handling

If an error occurs while retrieving the list of calls, the API will return an appropriate error response with a corresponding status code and error message in the response body.

For example, if the API key is missing or invalid:

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Make sure to handle errors appropriately in your application and provide the necessary authentication and query parameters.

Pagination

The Flyflow API supports pagination for the /calls endpoint to handle large numbers of calls efficiently. The response includes a cursor value that represents the starting point for the next page of results. To retrieve the next page, include the cursor value as a query parameter in the subsequent request.

For example, to retrieve the next page of calls:

curl -X GET \
  -H "Authorization: Bearer your_api_key" \
  "https://api.flyflow.dev/v1/calls?cursor=next_cursor_value&limit=20"

Continue using the cursor value from each response to navigate through the entire call history.

Conclusion

Retrieving a list of calls using the Flyflow API is a simple process. By making a GET request to the /calls endpoint, you can fetch paginated results of calls associated with your account. The API provides query parameters to control the number of calls returned and filter the results by agent and client number. The response includes a cursor value for pagination, allowing you to retrieve subsequent pages of results. Remember to handle errors and provide the necessary authentication and query parameters to ensure a smooth integration with the Flyflow platform.

Updated 6 months ago