Skip to main content
Aria Knowledge Central

Billie Connect Converse API V3 Specification

  1. Last updated
  2. Save as PDF

Overview

[Describe what this topic is about. In Aria application documentation, include a link to the corresponding API documentation for the same feature, and vice versa.

Example: This article provides the steps for creating a plan.]

Base URL

https://{api-gateway-domain}/api/v3/converse

Authentication

Same as v2 - Bearer token

Request Format

The request format is similar to v2 with an additional required field:

Additional Fields for v3

callback_url (required)

{ "callback_url": "string", "message_id": "string", "conversation_id": "string", "timestamp": "string", "response_preferences": { "include_textual_summary": boolean, "response_format": "STRUCTURED" | "TEXT" | "BOTH" }, "content": { "text": "string", "type": "QUERY" | "ACTION_REQUEST" | "ERROR", "structured_data": { "response_type": "string", "data": {}, "schema_version": "string" } }, "metadata": { "source_agent": "string", "target_agent": "string", "in_reply_to_message_id": "string", "sequence_num": number, "source_message_id": "string", "source_conversation_id": "string" } }
Field Type Required Description
callback_url string Yes* The Webhook Callback URL where Billie will post the response. This is a required field in the request but not in the response. ** For the current version, this should be an open POST endpoint where we will support secure callback URLs in future versions.

Response Format

Immediate Response (202 Accepted)

{ "message": "Request accepted for processing", "task_id": "task-789-xyz" }

Webhook Callback Structure

The actual response will be delivered to your callback_url with the same structure as v2:

Webhook Implementation Requirements

Your Webhook Endpoint Must:

  1. Accept POST requests with JSON payload

  2. Return 2xx status code to acknowledge receipt

  1. Signature Verification: Validate webhook signatures (implementation pending)

  2. HTTPS Only: Ensure callback URLs use HTTPS

  3. IP Whitelisting: Restrict webhook sources to known IP ranges (Pending)

  4. Idempotency: Handle duplicate webhook deliveries gracefully (Pending)

Usage Notes

  1. The callback URL is mandatory for every request (v3)

  2. Conversation Management:

    • Each conversation is identified by a unique conversation_id

    • Maintain sequence numbers for message ordering

    • Reference previous messages using in_reply_to_message_id

    • Conversation ID is required in the request from 2nd request in the same conversation.

    • Sharing source_message_id and source_conversation_id as meta data but not required.

  3. Response Preferences:

    • Set include_textual_summary: false to receive only structured data

    • Set response_format: "STRUCTURED" to optimize machine-to-machine communication

  4. Error Handling:

    • Error responses use the ERROR message type

    • Detailed error information is provided in structured_data

  5. Versioning:

    • Include schema_version in all structured data

    • The API version is part of the endpoint path

Examples

Example 1: Invoice Comparison

In this example an Agent called “agent_portal” is requesting to compare last 2 invoices for a specific account and requests the response to contain both the Conversational NL text as well as structured data.

Request:

{ "callback_url": "https://webhook.site/4a4a4107-a9ac-4f55-bb8c-9d84b0ee5505", "response_preferences": { "include_textual_summary": true, "response_format": "BOTH" }, "content": { "text": "Compare the last two invoices for account 25366939", "type": "QUERY" }, "metadata": { "source_agent": "agent_support", "target_agent": "agent_billie", "source_message_id": "smi-2", "source_conversation_id": "sci-2" } }
Webhook Response:{ "message_id": "msg_790", "conversation_id": "conv_457", "timestamp": "2025-02-27T01:36:05Z", "content": { "text": "Certainly, I’ll compare the last two invoices for account 25366939. Since you asked for a comparison between any two invoices, I will provide a comparison of the last two invoices available. The two invoices we’re comparing are: 1. Current invoice: 250610321 (February 2025) 2. Previous invoice: 246004138 (January 2025). Here’s a detailed comparison: 1. Monthly Fees: - Both invoices have a "Mobile Plan Monthly Fee" of $30.00. 2. Usage Charges: - Current invoice (February): No usage charges. - Previous invoice (January): * Talk: 125 minutes at $0.10/minute, totaling $12.50 * Text Messages: 227 messages at $0.75/message, totaling $170.25 * Data: 45 gigabytes at $0/GB (included in plan) and 21 gigabytes at $1.79/GB, totaling $37.59. 3. Taxes: - Current invoice (February): * State Taxes: $1.73 * County Taxes: $0.62 - Previous invoice (January): * State Taxes: $14.40 * County Taxes: $5.14. 4. Total Charges: - Current invoice (February): $32.35 - Previous invoice (January): $269.88. Key Observations: 1. The basic monthly fee remained constant at $30.00. 2. The February bill doesn’t show any usage charges, while January had significant charges for talk, text, and data usage. 3. Tax amounts are much lower in February, likely due to the absence of usage charges.", "type": "RESPONSE", "structured_data": { "response_type": "OPENDATA", "data": { "invoices": [ { "invoice_no": "250610321", "period": "February 2025", "monthly_fees": { "mobile_plan": 30.00 }, "usage_charges": { "talk": 0.00, "text": 0.00, "data": 0.00 }, "taxes": { "state": 1.73, "county": 0.62 }, "total": 32.35 }, { "invoice_no": "246004138", "period": "January 2025", "monthly_fees": { "mobile_plan": 30.00 }, "usage_charges": { "talk": { "minutes": 125, "rate": 0.10, "total": 12.50 }, "text": { "messages": 227, "rate": 0.75, "total": 170.25 }, "data": { "included_gb": 45, "extra_gb": 21, "rate": 1.79, "total": 37.59 } }, "taxes": { "state": 14.40, "county": 5.14 }, "total": 269.88 } ], "comparison": { "total_difference": -237.53, "percentage_change": -88.01 } }, "schema_version": "1.0" } }, "metadata": { "source_agent": "agent_billie", "target_agent": "agent_support", "in_reply_to_message_id": "msg_124", "sequence_num": 1, "source_conversation_id": "sci-2" } }

Example 3: Pending Invoice Approval

In this example an Agent called “agent_finance” is requesting whether there are any pending invoices for a specific account and requests the response to contain both the Conversational NL text as well as structured data.

As a follow up, “agent_finance” is requesting [ ACTION REQUEST] to approve the given invoice and requests to contain both Conversational NL text as well as structured data.

Request:

{ "callback_url": "https://webhook.site/4a4a4107-a9ac-4f55-bb8c-9d84b0ee5505", "response_preferences": { "include_textual_summary": true, "response_format": "BOTH" }, "content": { "text": "Approve the pending invoice for account filC3470", "type": "ACTION_REQUEST" }, "metadata": { "source_agent": "agent_finance", "target_agent": "agent_billie", "source_message_id": "smi-3", "source_conversation_id": "sci-3" } }

Webhook Response:

{ "message_id": "msg_126", "conversation_id": "conv_458", "timestamp": "2025-02-27T05:41:05Z", "content": { "text": "Certainly. I can help you approve the pending invoice for account filC3470. There are multiple pending invoices for this account. Please refer to the list below to select the specific invoice you’d like to approve. To approve a specific invoice, please provide the invoice number you wish to approve. Invoice 7713191, Invoice 7713192, Invoice 7713193, Invoice 7713199.", "type": "RESPONSE", "structured_data": { "response_type": "OPENDATA", "data": { "account_no": "2134455", "client_account_id": "filC3470", "pending_invoices": [ {"invoice_no": "7713191", "status": "PENDING"}, {"invoice_no": "7713192", "status": "PENDING"}, {"invoice_no": "7713193", "status": "PENDING"}, {"invoice_no": "7713199", "status": "PENDING"} ], "action_required": "SELECT_INVOICE" }, "schema_version": "1.0" } }, "metadata": { "source_agent": "agent_billie", "target_agent": "agent_finance", "in_reply_to_message_id": "msg_125", "sequence_num": 1, "source_conversation_id": "sci-3" } }

Follow-up Request:

{ "callback_url": "https://webhook.site/4a4a4107-a9ac-4f55-bb8c-9d84b0ee5505", "message_id": "msg_127", "conversation_id": "conv_458", "timestamp": "2025-02-27T05:41:30Z", "response_preferences": { "include_textual_summary": true, "response_format": "BOTH" }, "content": { "text": "Approve invoice 7713191", "type": "ACTION_REQUEST", "structured_data": { "response_type": "OPENDATA", "data": { "action": "APPROVE", "invoice_no": "7713191" }, "schema_version": "1.0" } }, "metadata": { "source_agent": "agent_finance", "target_agent": "agent_billie", "in_reply_to_message_id": "msg_126", "sequence_num": 2, "source_message_id": "smi-5", "source_conversation_id": "sci-3" } }

Final Webhook Response:

{ "message_id": "msg_128", "conversation_id": "conv_458", "timestamp": "2025-02-27T05:42:00Z", "content": { "text": "The invoice 7713191 has been successfully approved. The invoice status has been updated to Bill Through Partner, and a comment has been added to the account.", "type": "ACTION_RESULT", "structured_data": { "response_type": "ACTION_RESULT", "data": { "success": true, "invoice_no": "7713191", "account_no": "filC3470", "status": "BILL_THROUGH_PARTNER", "comments_added": true }, "schema_version": "1.0" } }, "metadata": { "source_agent": "agent_billie", "target_agent": "agent_finance", "in_reply_to_message_id": "msg_127", "sequence_num": 3, "source_conversation_id": "sci-3" } }
TOP
  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Page type
    Topic
  2. Tags
    This page has no tags.