Back to documentations

Back to documentations

How to Use Aurora Flask API

How to Use Aurora Flask API

How to Use Aurora Flask API

This is a guide for API usage.

This is a guide for API usage.

1. Overview

This API handles multiple types of requests, including webhook requests for agent assistants operations, where it retrieves configuration data from the database, and manages end-of-call report handling. It also facilitates chat interactions by integrating with Swarm OpenAI agents to generate real-time AI responses. Additionally, the API supports function handling, allowing Swarm agents to access and execute specific tasks or commands, and it can generate weekly reports by aggregating and summarizing relevant data from interactions and activities.

This API handles multiple types of requests, including webhook requests for agent assistants operations, where it retrieves configuration data from the database, and manages end-of-call report handling. It also facilitates chat interactions by integrating with Swarm OpenAI agents to generate real-time AI responses. Additionally, the API supports function handling, allowing Swarm agents to access and execute specific tasks or commands, and it can generate weekly reports by aggregating and summarizing relevant data from interactions and activities.

2. Authentication

The API supports three types of authentication methods:

  • Authorization (Bearer Token): Used for the /api/v1/openai/chat/completions endpoint, where requests must include a Bearer token for authentication.

  • BINARYTINT_API_KEY: Used for the /api/webhook endpoint, where an API key is required in the header for access.

  • BINARYTINT-INTERNAL-API-KEY: Required for the /api/reports/ and /api/outbound-call-uat endpoints, where the internal API key is used for authentication.

  • BINARYTINT-EXTERNAL-API-KEY: Required for the /api/outbound-call-uat endpoint, where the external API key is used for authentication from external sources (users of our api, for now lamantic.ai).

The API supports three types of authentication methods:

  • Authorization (Bearer Token): Used for the /api/v1/openai/chat/completions endpoint, where requests must include a Bearer token for authentication.

  • BINARYTINT_API_KEY: Used for the /api/webhook endpoint, where an API key is required in the header for access.

  • BINARYTINT-INTERNAL-API-KEY: Required for the /api/reports/ and /api/outbound-call-uat endpoints, where the internal API key is used for authentication.

  • BINARYTINT-EXTERNAL-API-KEY: Required for the /api/outbound-call-uat endpoint, where the external API key is used for authentication from external sources (users of our api, for now lamantic.ai).

3. Endpoints & Usage

  1. The /api/webhook endpoint - handles multiple payload type

    1. assistant-request

      1. Retrieves assistant configuration

      2. Example:

  1. The /api/webhook endpoint - handles multiple payload type

    1. assistant-request

      1. Retrieves assistant configuration

      2. Example:

POST {base_url}/api/webhook
Headers:
  Content-Type: application/json
  FLASK-API-KEY: <BINARYTINT_API_KEY>

Body:
{
  "message": {
    "type": "assistant-request",
    "session": "{session}"
  }
}

iii. Response:

iii. Response:

Response Status: 201
Response Body: {
  "assistantId": "<assistantId>",
  "aiResponseLengthMinimum": "<aiResponseLengthMinimum>",
  "assistantFirstMessage": "<assistantFirstMessage>",
  "assistantName": "<assistantName>",
  "assistantPhoneNumber": "<assistantPhoneNumber>",
  "assistantPhoneNumberName": "<assistantPhoneNumberName>",
  "assistantPrompt": "<assistantPrompt>",
  "deepgramModel": "<deepgramModel>",
  "elevenLabsModel": "<elevenLabsModel>",
  "elevenLabsVoiceId": "<elevenLabsVoiceId>",
  "emails": ["<email1>", "<email2>"],
  "functions": ["<function1>", "<function2>"],
  "gracePeriodMs": "<gracePeriodMs>",
  "minimumTimeBeforeAiResponds": "<minimumTimeBeforeAiResponds>",
  "orgName": "<orgName>",
  "phoneNumbers": ["<phoneNumber1>", "<phoneNumber2>"],
  "quickFinalizeDelayMs": "<quickFinalizeDelayMs>",
  "textFromNumber": "<textFromNumber>",
  "timeZone": "<timeZone>"
}

  1. end-of-call-report

    1. Generates summary and uploads eoc report to aws

    2. Example:

  1. end-of-call-report

    1. Generates summary and uploads eoc report to aws

    2. Example:

POST {base_url}/api/webhook
Headers:
  Content-Type: application/json
  FLASK-API-KEY: <BINARYTINT_API_KEY>

Body: {
  "message": {
    "type": "end-of-call-report",
    "endedReason": "<endedReason>",
    "call": {
      "id": "<callId>",
      "assistantId": "<assistantId>",
      "customer": {
        "number": "<customerNumber>"
      },
      "type": "<callType>",
      "status": "<callStatus>",
      "twilioNumber": "<twilioNumber>",
      "cost": "<callCost>",
      "duration": "<callDuration>"
    },
    "recordingUrl": "<recordingUrl>",
    "messages": "<messages>",
    "summary": "<summary>",
    "transcript": "<transcript>",
    "customer": {
      "number": "<customerNumber>",
      "name": "<customerName>"
    },
    "timestamp": "<timestamp>",
    "phoneCallProvider": "<phoneCallProvider>"
  }
}

c. Response:

c. Response:

Response Status: 200
Response Body: {}

  1. The /api/v1/openai/chat/completions endpoint

    1. Facilitates chat interactions by integrating with Swarm OpenAI agents to generate real-time AI responses

    2. Example:

  1. The /api/v1/openai/chat/completions endpoint

    1. Facilitates chat interactions by integrating with Swarm OpenAI agents to generate real-time AI responses

    2. Example:

POST {base_url}/api/v1/openai/chat/completions
Headers:
  Content-Type: application/json
  Authorization: Bearer <BINARYTINT_API_KEY>

Body: {
  "model": "<gpt-model>",
  "messages": "<messages>",
  "temperature": <temperature>,
  "stream": <stream>,
  "call": {
    "id": "<session.streamSid>",
    "caller_phone_number": "<session.callerPhoneNumber>",
    "assistant_config": "<session.assistant_config>"
  }
}

c. Response Streaming:

c. Response Streaming:

Response Status: 200
Response Body:
  data: {
    "choices": [{
      "delta": {
        "content": "<chunkContent>"
      },
      "index": 0,
      "finish_reason": null
    }],
    "model": "<model>"
  }

  data: {
    "choices": [{
      "delta": {},
      "index": 0,
      "finish_reason": "stop"
    }],
    "model": "<model>"
  }

  data: {
    "full_session": "<updatedSession>"
  }

  data: [DONE]

d. Response Non-Streaming:

d. Response Non-Streaming:

Response Status: 200
Response Body: {
  "id": "<chatCompletionId>",
  "object": "chat.completion",
  "created": <timestamp>,
  "model": "<model>",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "<assistantResponse>",
      "tools_calls": "<toolCalls>"
    },
    "finish_reason": "stop",
    "index": 0
  }],
  "full_session": "<updatedSession>"
}

  1. The /api/v1/openai/chat/completions/voice endpoint

    1. Facilitates voice-based interactions. Supports both streaming and non-streaming responses.

    2. Behavior:

      1. Streaming: Streams assistant responses via Server-Sent Events (SSE).

      2. Non-Streaming: Returns a full assistant response in a single JSON payload.

    3. Example Streaming Logic:

      1. Incoming: Full messages conversation and call data (including id, caller_phone_number, assistant_config).

      2. Processing: Uses stream_process_messages() for real-time response generation.

      3. Output:

        1. Incremental chunks (content) streamed.

        2. full_session sent after message completion.

        3. DONE signals end of stream.

    4. Example:

  1. The /api/v1/openai/chat/completions/voice endpoint

    1. Facilitates voice-based interactions. Supports both streaming and non-streaming responses.

    2. Behavior:

      1. Streaming: Streams assistant responses via Server-Sent Events (SSE).

      2. Non-Streaming: Returns a full assistant response in a single JSON payload.

    3. Example Streaming Logic:

      1. Incoming: Full messages conversation and call data (including id, caller_phone_number, assistant_config).

      2. Processing: Uses stream_process_messages() for real-time response generation.

      3. Output:

        1. Incremental chunks (content) streamed.

        2. full_session sent after message completion.

        3. DONE signals end of stream.

    4. Example:

POST {base_url}/api/v1/openai/chat/completions/voice
Headers:
  Content-Type: application/json
  Authorization: Bearer <BINARYTINT_API_KEY>

Body: {
  "model": "<gpt-model>",
  "messages": "<messages>",
  "temperature": <temperature>,
  "stream": <stream>,
  "call": {
    "id": "<call.id>",
    "caller_phone_number": "<call.callerPhoneNumber>",
    "assistant_config": "<call.assistantConfig>"
  }
}

e. Response Streaming:

e. Response Streaming:

Response Status: 200
Response Body:
data: {
  "choices": [{
    "delta": {
      "content": "<chunkContent>"
    },
    "index": 0,
    "finish_reason": null
  }],
  "model": "<model>"
}

data: {
  "choices": [{
    "delta": {},
    "index": 0,
    "finish_reason": "stop"
  }],
  "model": "<model>"
}

data: {
  "full_session": "<updatedSession>"
}

data: [DONE]

f. Response Non-Streaming:

f. Response Non-Streaming:

Response Status: 200
Response Body: {
  "id": "<chatCompletionId>",
  "object": "chat.completion",
  "created": <timestamp>,
  "model": "<model>",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "<assistantResponse>",
      "tools_calls": "<toolCalls>"
    },
    "finish_reason": "stop",
    "index": 0
  }],
  "full_session": "<updatedSession>"
}

  1. The /api/v1/openai/chat/completions/sms endpoint

    1. Handles SMS-based interactions without streaming.

    2. Behavior:

      1. Input: Full conversation (messages) and optional call metadata.

      2. Processing: Uses process_sms_messages() to generate a concise text reply.

      3. Output: Returns a single assistant response with updated session data.

    3. Example:

  1. The /api/v1/openai/chat/completions/sms endpoint

    1. Handles SMS-based interactions without streaming.

    2. Behavior:

      1. Input: Full conversation (messages) and optional call metadata.

      2. Processing: Uses process_sms_messages() to generate a concise text reply.

      3. Output: Returns a single assistant response with updated session data.

    3. Example:

POST {base_url}/api/v1/openai/chat/completions/sms
Headers:
  Content-Type: application/json
  Authorization: Bearer <BINARYTINT_API_KEY>

Body: {
  "model": "<gpt-model>",
  "messages": "<messages>",
  "call": {
    "id": "<call.id>",
    "caller_phone_number": "<call.callerPhoneNumber>",
    "assistant_config": "<call.assistantConfig>"
  }
}

d. Response Streaming:

d. Response Streaming:

Response Status: 200
Response Body:
  {
  "id": "<chatCompletionId>",
  "object": "chat.completion",
  "created": <timestamp>,
  "model": "<model>",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "<assistantResponse>"
    },
    "finish_reason": "stop",
    "index": 0
  }],
  "full_session": "<updatedSession>"
}

  1. The /api/v1/openai/chat/completions/chat endpoint

    1. Facilitates web-chat style interactions, optimized for chatbot use-cases.

    2. Behavior:

      1. Input: Requires messages, call, and mandatory target_assistant_id.

      2. Processing: Calls process_messages_for_chat_assistant().

      3. Output: Returns a detailed assistant reply with optional tool calls.

    3. Example:

  1. The /api/v1/openai/chat/completions/chat endpoint

    1. Facilitates web-chat style interactions, optimized for chatbot use-cases.

    2. Behavior:

      1. Input: Requires messages, call, and mandatory target_assistant_id.

      2. Processing: Calls process_messages_for_chat_assistant().

      3. Output: Returns a detailed assistant reply with optional tool calls.

    3. Example:

POST {base_url}/api/v1/openai/chat/completions/chat
Headers:
  Content-Type: application/json
  Authorization: Bearer <BINARYTINT_API_KEY>

Body: {
  "model": "<gpt-model>",
  "messages": "<messages>",
  "call": {
    "id": "<call.id>",
    "assistant_config": "<call.assistantConfig>"
  },
  "target_assistant_id": "<targetAssistantId>"
}

d. Response Streaming:

d. Response Streaming:

Response Status: 200
Response Body:
{
  "id": "<chatCompletionId>",
  "object": "chat.completion",
  "created": <timestamp>,
  "model": "<model>",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "<assistantResponse>",
      "tools_calls": "<toolCalls>"
    },
    "finish_reason": "stop",
    "index": 0
  }]
}

  1. The /api/reports/aurora-report/<string:period_type> endpoint

    1. This endpoint is used to generate an aggregated report for a specific AI assistant. It supports two report types, weekly and monthly, which are specified in the URL path. The function retrieves relevant data from assistant interactions and activities to compile a comprehensive summary.

    2. Weekly report

      1. Example:

  1. The /api/reports/aurora-report/<string:period_type> endpoint

    1. This endpoint is used to generate an aggregated report for a specific AI assistant. It supports two report types, weekly and monthly, which are specified in the URL path. The function retrieves relevant data from assistant interactions and activities to compile a comprehensive summary.

    2. Weekly report

      1. Example:

POST {base_url}/api/reports/aurora-report/weekly
Headers:
  BINARYTINT-INTERNAL-API-KEY: <BINARYTINT-INTERNAL-API-KEY>

Body: {
  "ASSISTANT_ID": "string"
}

ii. Response:

ii. Response:

Response Status: 200
Response Body:
{
  "status": "success",
  "message": "Weekly report generated successfully for assistant 9395bc40-ee5d-47e1-bcf3-b2af2f63e84a"
}

c. Monthly report
i. Example:

c. Monthly report
i. Example:

POST {base_url}/api/reports/aurora-report/monthly
Headers:
  BINARYTINT-INTERNAL-API-KEY: <BINARYTINT-INTERNAL-API-KEY>

Body: {
  "ASSISTANT_ID": "string"
}

ii. Response:

ii. Response:

Response Status: 200
Response Body:
{
  "status": "success",
  "message": "Monthly report generated successfully for assistant 9395bc40-ee5d-47e1-bcf3-b2af2f63e84a"
}

  1. The /api/reports/aurora-internal-report/<string:period_type> endpoint

    1. This endpoint generates a weekly or monthly report for all internal assistants that have been configured. This is typically triggered by an internal automation tool.Parameters:

      1. period_type (path parameter): A string specifying the report period. Must be either weekly or monthly.

    2. Example:

  1. The /api/reports/aurora-internal-report/<string:period_type> endpoint

    1. This endpoint generates a weekly or monthly report for all internal assistants that have been configured. This is typically triggered by an internal automation tool.Parameters:

      1. period_type (path parameter): A string specifying the report period. Must be either weekly or monthly.

    2. Example:

POST {base_url}/api/reports/aurora-internal-report/weekly
Header:
BINARYTINT-INTERNAL-API-KEY : <BINARYTINT-INTERNAL-API-KEY

c. Response:

c. Response:

{
  "status": "success",
  "message": "Internal report generation process started for all assistants for the weekly period."
}

  1. The /api/outbound-call-uat endpoint

    1. This endpoint initiates an outbound call to a specified client on behalf of an AI assistant. It requires a client's details and an assistant's unique ID to start the conversation.

    2. This endpoint can be accessed with either a valid BINARYTINT-INTERNAL-API-KEY or BINARYTINT-EXTERNAL-API-KEY provided in the request headers. If neither is valid, the request will be rejected with a 401 Unauthorized status.

    3. Example:

  1. The /api/outbound-call-uat endpoint

    1. This endpoint initiates an outbound call to a specified client on behalf of an AI assistant. It requires a client's details and an assistant's unique ID to start the conversation.

    2. This endpoint can be accessed with either a valid BINARYTINT-INTERNAL-API-KEY or BINARYTINT-EXTERNAL-API-KEY provided in the request headers. If neither is valid, the request will be rejected with a 401 Unauthorized status.

    3. Example:

POST {base_url}/api/outbound-call-uat
Headers:
  Content-Type : application/json
  BINARYTINT-EXTERNAL-API-KEY: <BINARYTINT-EXTERNAL-API-KEY> or
  BINARYTINT-INTERNAL-API-KEY : <BINARYTINT-INTERNAL-API-KEY>

Body:
{
  "client": {
    "phoneNumber": "string",
    "name": "string",
    "email": "string"
  },
  "assistantId": "string"
}

d. Response:

d. Response:

{
    "data": "Call initiated from assistaintPhoneNumber = {assistaintPhoneNumber} to {name} at {phoneNumber}. Call sid = {call_sid}",
    "status": "success"
}

  1. The /api/hyperscale/outbound-call endpoint

    1. This endpoint initiates an outbound call to a specified client. Unlike the outbound-call-uat endpoint, this one uses a hardcoded assistantId and is intended for a specific use case where client information is provided directly.

    2. This endpoint accepts either a valid BINARYTINT-INTERNAL-API-KEY or BINARYTINT-EXTERNAL-API-KEY in the request headers. Requests without a valid key will be rejected with a 401 Unauthorized status.

    3. Request:

  1. The /api/hyperscale/outbound-call endpoint

    1. This endpoint initiates an outbound call to a specified client. Unlike the outbound-call-uat endpoint, this one uses a hardcoded assistantId and is intended for a specific use case where client information is provided directly.

    2. This endpoint accepts either a valid BINARYTINT-INTERNAL-API-KEY or BINARYTINT-EXTERNAL-API-KEY in the request headers. Requests without a valid key will be rejected with a 401 Unauthorized status.

    3. Request:

POST {base_url}/api/hyperscale/outbound-call
Headers:
  Content-Type : application/json
  BINARYTINT-EXTERNAL-API-KEY: <BINARYTINT-EXTERNAL-API-KEY> or
  BINARYTINT-INTERNAL-API-KEY : <BINARYTINT-INTERNAL-API-KEY>

Body:
  {
  "phoneNumber": "string",
  "name": "string",
  "info": "string"
  }

d. Response:

d. Response:

Response Status: 200
Response Body:
{
    "data": "Call initiated from assistaintPhoneNumber = {assistaintPhoneNumber} to {name} at {phoneNumber}. Call sid = {callSid}",
    "status": "success"
}

e. Example:

e. Example:

POST {base_url}/api/hyperscale/outbound-call
Headers:
  Content-Type : application/json
  BINARYTINT-EXTERNAL-API-KEY: <BINARYTINT-EXTERNAL-API-KEY> or
  BINARYTINT-INTERNAL-API-KEY : <BINARYTINT-INTERNAL-API-KEY>

Body:
{
      "phoneNumber": "+40742070688",
      "name": "John Doe",
      "info": "Some relevant info"
}

i. Response:

i. Response:

Response Status: 200
Response Body:
{
    "data": "Call initiated from assistaintPhoneNumber = 4639465275 to John Doe at +40742070688. Call sid = CAdfbe15114bfabe08c3c017dcdea96264",
    "status": "success"
}

Smarter Conversations Start Here

Smarter Conversations Start Here

Smarter Conversations Start Here

With VoxSuite, you can deliver better customer service while saving time and money. Let Aurora do the heavy lifting, so you can focus on what matters most.

With VoxSuite, you can deliver better customer service while saving time and money. Let Aurora do the heavy lifting, so you can focus on what matters most.

Book an Aurora Demo

Book an Aurora Demo

Book an Aurora Demo

Aurora Logo

131 Continental Dr. Suite 305,

Newark DE 197130

United States

Quick Links

Home

We Are Here To Help

Press

Partners

Voxify Infrastructure Status

Privacy Policy

Website Tracking Policy

Terms of Use

Service Level Agreement

Book an Aurora Demo

© 2025 Voxify. All rights reserved.

Aurora Logo

131 Continental Dr. Suite 305,

Newark DE 197130

United States

Quick Links

Home

We Are Here To Help

Press

Partners

Voxify Infrastructure Status

Privacy Policy

Website Tracking Policy

Terms of Use

Service Level Agreement

Book an Aurora Demo

© 2025 Voxify. All rights reserved.

Aurora Logo

131 Continental Dr. Suite 305,

Newark DE 197130

United States

Quick Links

Home

We Are Here To Help

Press

Partners

Voxify Infrastructure Status

Privacy Policy

Website Tracking Policy

Terms of Use

Service Level Agreement

Book an Aurora Demo

© 2025 Voxify. All rights reserved.