Create a Call

The Flyflow API allows you to create a new call by making a POST request to the /call endpoint. This endpoint initiates a call between a specified agent and a recipient phone number.

Request

Endpoint

POST /call

Headers

• Authorization: The API key prefixed with Bearer. Example: Bearer your_api_key.
• Content-Type: The content type of the request body. Must be set to application/json.

Request Body

The request body should be a JSON object containing the following properties:

• from (string, required): The phone number of the agent initiating the call. This must be a valid phone number associated with an existing agent.
• to (string, required): The recipient phone number to call. This must be a valid phone number.
• context (string, optional): The initial context or message to be used for the call. This can provide additional information or context for the agent.
• user_speaks_first (bool, optional): Flag for if the user or agent should start the conversation

cURL Example

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+1234567890",
    "to": "+9876543210",
    "context": "Hello, this is an important call.",
    "user_speaks_first": true
  }' \
  "https://api.flyflow.dev/v1/call"

Python Client Example

from flyflowclient import Flyflow

client = Flyflow(api_key='your_api_key')

call = client.create_call(
    from_number='+1234567890',
    to_number='+9876543210',
    context='Hello, this is an important call.',
  	user_speaks_first: True
)

print(call)

Response

Status Codes

• 200 OK: The call was successfully created.
• 400 Bad Request: The request body is missing required fields or contains invalid data.
• 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 call is successfully created, the response body will be a JSON object containing the details of the created call:

{
  "id": "call_id",
  "agent_id": "agent_id",
  "from": "+1234567890",
  "to": "+9876543210",
  "context": "Hello, this is an important call.",
  "status": "queued",
  "created_at": "timestamp"
}

• id (string): The unique identifier of the created call.
• agent_id (string): The identifier of the agent associated with the call.
• from (string): The phone number of the agent initiating the call.
• to (string): The recipient phone number.
• context (string): The initial context or message provided for the call.
• status (string): The current status of the call. Initially set to "queued".
• created_at (string): The timestamp indicating when the call was created.

Error Handling

If an error occurs during the call creation process, the API will return an appropriate error response with a corresponding status code and error message in the response body.

For example, if the request body is missing required fields:

{
  "error": "Bad Request",
  "message": "Missing required fields: from, to"
}

Make sure to handle errors appropriately in your application and provide the necessary information in the request body.

Conclusion

Creating a call using the Flyflow API is a straightforward process. By making a POST request to the /call endpoint with the required information in the request body, you can initiate a call between an agent and a recipient phone number. The API will return the details of the created call upon success. Remember to handle errors and provide the necessary authentication and request parameters to ensure a smooth integration with the Flyflow platform.