Skip to main content
Aria Knowledge Central

Billie Connect Converse API V2 Specification

  1. Last updated
  2. Save as PDF

Note: Aria recommends using version 2 for most circumstances. However, if you experience excessive timeouts with version 2, Aria recommends using version 3. Please see the Version 2 vs. Version 3 article for more details, including respective API endpoints.

  1. Base URL
  2. Authentication
    1. Headers Required:
    2. Request Body:
    3. Response:
    4. Status Codes:
  3. Data Models
    1. AgentMessage
  4. Response Preferences
  5. Content
  6. MessageType
  7. StructuredResponse
  8. StructuredResponseType
  9. Response Data types
    1. INVOICE_INFO Response Structure
      1. InvoiceInfo (Root Object)
      2. InvoiceList
      3. Invoice
    2. BILL_ESTIMATE Response Structure
      1. BillEstimate (Root Object)
      2. SummaryEstimatedCharge
      3. DetailedEstimatedCharge
      4. RecurringChargeDetail
      5. OnetimeChargeDetail
      6. UsageChargeDetail
      7. UsageTypeGroupDetail
    3. CONTRACT_INFO Response Structure
      1. ContractInfo (Root Object)
      2. ContractOverview
      3. ContractDuration
      4. ContractRenewal
      5. ContractCancellation
      6. SubscriptionAssociated
      7. RolloverInfo
      8. ContractMetadata
    4. Metadata
    5. Structured Response Support
      1. Supported Structured Response Types
  10. Structured Response Format
    1. Response Format Options
  11. Examples
    1. Example 1: Account Summary

Base URL

POST https://{api-gateway-domain}/api/v2/converse

Authentication

Headers Required:

Authorization: Bearer {jwt_token}
Content-Type: application/json

Request Body:

{
  "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"
  }
}

Response:

{
  "message_id": "string",
  "conversation_id": "string",
  "timestamp": "string",
  "content": {
    "text": "string",
    "type": "RESPONSE" | "ACTION_RESULT" | "ERROR",
    "structured_data": {
      "response_type": "ACCOUNT_INFO" | "BILLING_INFO" | "INVOICE_INFO" | "ORDER_INFO" | "PRODUCT_INFO" | "ERROR_DETAILS" | "ACTION_RESULT" | "OPENDATA",
      "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",
  }
}

Status Codes:

200 OK: Message processed successfully

400 Bad Request: Invalid request format

401 Unauthorized: Invalid auth token, Unauthorized request

404 Not Found: Requested resource not found

500 Internal Server Error: Server error

403 Forbidden:  Billie not enabled

Data Models

AgentMessage

Field Type Required Description
message_id string No* Unique identifier for the message. *This is required in the response.
conversation_id string No * Groups related messages together. *This is required from the 2nd message onward in a same conversation in both response and request.
timestamp string No ISO 8601 format timestamp
response_preferences object No Preferences for response format
content object Yes Message content
metadata object Yes Additional message metadata

Response Preferences

Field Type Required Description
include_textual_summary boolean No Controls whether to include text summary. Default value is true if not specified.
response_format string No Desired response format: "STRUCTURED", "TEXT", or "BOTH" . Default value is "TEXT" if not specified.

Content

Field Type Required Description
text string No* Natural language content (*Required for TEXT format)
type string Yes Type of message (see MessageType)
structured_data object No* Structured data (*Required for STRUCTURED format)

MessageType

Value Description
QUERY Questions or information requests
RESPONSE Answers or information provision
ERROR Error conditions
ACTION_REQUEST Requests for specific actions
ACTION_RESULT Results of requested actions

StructuredResponse

Field Type Required Description
response_type string Yes Type of structured response
data object Yes Response data
schema_version string Yes Version of the response schema

StructuredResponseType

Value Description
ACCOUNT_INFO Account information
BILLING_INFO Billing information
INVOICE_INFO Invoice information
ORDER_INFO Order information
PRODUCT_INFO Product information
ERROR_DETAILS Detailed error information
ACTION_RESULT Results of an action
OPENDATA Custom data structure
BILL_ESTIMATE Bill estimations structure

Response Data types

ACCOUNT_INFO, INVOICE_INFO, BILL_ESTIMATE

INVOICE_INFO Response Structure

InvoiceInfo (Root Object)

Field Type Description
invoice_list InvoiceList List of invoices with associated data

InvoiceList

Field Type Description
data Invoice[] Array of invoice records

Invoice

Field Type Description
invoice_no string Invoice number
acct_no string Account number
client_acct_id string Client account identifier
amount float Invoice amount
bill_date string Date when the invoice was billed
due_date string Expected due date for payment
paid_date string Date when the invoice was paid
notify_date string Date when notification was sent
recurring_bill_from_date string Start date for recurring billing period
recurring_bill_thru_date string End date for recurring billing period
currency_cd string Currency code
balance_forward float Balance carried forward from previous invoices
total_due float Total amount due
comments string Invoice comments
additional_comments string Additional comments
last_updated string Timestamp when invoice was last updated
user_id string User identifier
aria_statement_no string Aria statement number
custom_status_label string Custom status label
client_notes string Client notes
invoice_type_cd string Invoice type code
billing_group_no string Billing group number
usage_bill_from_date string Start date for usage billing period
usage_bill_thru_date string End date for usage billing period
overall_bill_from_date string Start date for overall billing period
overall_bill_thru_date string End date for overall billing period

BILL_ESTIMATE Response Structure

BillEstimate (Root Object)

Field Type Description
recorded_summary_estimated_charges SummaryEstimatedCharge[] Summary of recorded estimated charges
recorded_detailed_estimated_charges DetailedEstimatedCharge[] Detailed breakdown of recorded estimated charges
current_period_summary_estimated_charges SummaryEstimatedCharge[] Summary of current period estimated charges
current_period_detailed_estimated_charges DetailedEstimatedCharge[] Detailed breakdown of current period estimated charges
multiple_period_summary_estimated_charges SummaryEstimatedCharge[] Summary of multiple period estimated charges
multiple_period_detailed_estimated_charges DetailedEstimatedCharge[] Detailed breakdown of multiple period estimated charges

SummaryEstimatedCharge

Field Type Description
activation_charges float Total activation charges (default: 0.0)
usage_charges float Total usage charges (default: 0.0)
onetime_charges float Total one-time charges (default: 0.0)
recurring_charges float Total recurring charges (default: 0.0)
subscription_no string Subscription number (default: "")

DetailedEstimatedCharge

Field Type Description
subscription_no string Subscription number
recurring_charge_details RecurringChargeDetail[] List of recurring charge details
onetime_charge_details OnetimeChargeDetail[] List of one-time charge details
usage_charge_details UsageChargeDetail[] List of usage charge details
activation_charges float Total activation charges (default: 0.0)

RecurringChargeDetail

Field Type Description
subscription_no string Subscription number
service_description string Description of the service
subscription_units integer Number of subscription units
amount float Charge amount
subscription_name string Name of the subscription

OnetimeChargeDetail

Field Type Description
description string Description of the charge
amount float Charge amount
order_no string Order number

UsageChargeDetail

Field Type Description
usage_type_code string Code identifying the usage type
usage_type_description string Description of the usage type
tiered_pricing_rule integer Tiered pricing rule identifier
usage_units_description string Description of usage units
usage_type_group_details UsageTypeGroupDetail[] List of usage type group details

UsageTypeGroupDetail

Field Type Description
usage_units float Number of usage units
rate float Rate per unit
amount float Total amount for this usage group
rate_seq_no integer Rate sequence number

CONTRACT_INFO Response Structure

ContractInfo (Root Object)

Field Type Description
overview ContractOverview Overview information about the contract
duration ContractDuration Contract duration details
renewal ContractRenewal Contract renewal information
cancellation ContractCancellation Contract cancellation details
subscriptions_associated SubscriptionAssociated[] List of subscriptions associated with this contract
metadata ContractMetadata Contract metadata

ContractOverview

Field Type Description
contract_name string Name of the contract
contract_no string Contract number
contract_type string Type of contract
contract_type_desc string Description of the contract type
contract_end_action string Action to take at contract end
contract_end_action_no integer Contract end action number
contract_end_action_desc string Description of contract end action
contract_status string Current contract status
contract_status_no integer Contract status number

ContractDuration

Field Type Description
completion_type string Type of completion
type string Duration type
length integer Duration length
start_date string Contract start date
end_date string Contract end date

ContractRenewal

Field Type Description
will_renew boolean Whether the contract will renew
renewal_completion_type string Type of renewal completion
new_duration_type string New duration type after renewal
new_duration_length integer New duration length after renewal
new_end_date string New end date after renewal

ContractCancellation

Field Type Description
has_cancellation_fee boolean Whether there is a cancellation fee
cancellation_fee float Amount of cancellation fee

SubscriptionAssociated

Field Type Description
subscription_no string Subscription number
subscription_name string Subscription name
status string Subscription status
rollover_info RolloverInfo Rollover information for this subscription

RolloverInfo

Field Type Description
will_rollover boolean Whether the subscription will rollover
rollover_subscription_name string Name of the rollover subscription
rollover_subscription_no string Number of the rollover subscription
rollover_rate_schedule_name string Name of the rollover rate schedule
rollover_rate_schedule_no string Number of the rollover rate schedule

ContractMetadata

Field Type Description
created_date string Date when the contract was created
last_updated string Date when the contract was last updatedxxx

Metadata

Field Type Required Description
source_agent string Yes Identity of the sending agent
target_agent string No Identity of the intended recipient
in_reply_to_message_id string No ID of the message this is responding to
sequence_num number No Position in conversation
source_message_id string No Source(client) message ID
source_conversation_id string No Source(client) conversation ID

Structured Response Support

Both v2 and v3 APIs support structured data responses for specific intent types. When response_format is set to "STRUCTURED" or "BOTH", the API will return machine-readable structured data in addition to or instead of text responses.

Supported Structured Response Types

Intent Description Available Data
LIST_RECENT_INVOICES List of recent invoices Invoice numbers, amounts, dates, status
COMPARE_LAST_TWO_INVOICES COMPARE_TWO_SPECIFIC_INVOICES Comparison between two invoices Line-by-line differences, amount changes, date comparisons
CREATE_CASH_CREDIT Cash credit application details Requested amount, reason, account information
CONFIRM_CREATE_CASH_CREDIT Cash credit confirmation status Approval status, reference number, amount confirmed
CREATE_STANDALONE_SERVICE_CREDIT Service credit application result Credit amount, service details, application status
EXPLAIN_LAST_INVOICE Detailed invoice breakdown Line items, charges, taxes, credits
RECOMMEND_PLANS Recommended plans based on usage Plan details, cost savings, feature comparisons
UPDATE_PLAN_RATE_SCHEDULE Rate schedule update confirmation New rates, effective dates, impact summary

Structured Response Format

When structured data is available, responses include a structured_data field:

{ "content": { "type": "RESPONSE", "text": "Here are your recent invoices...", "structured_data": { "response_type": "INVOICE_INFO", "data": { "invoice_list": { "invoices": [ { "invoice_no": "23453435", "amount": 150.00, "created_date": "2024-01-01", "due_date": "2024-01-31", "status": "PAID" } ] } }, "schema_version": "1.0" } } }

Response Format Options

  • TEXT: Text-only response (traditional conversational format)

  • STRUCTURED: Structured data only (machine-readable format)

  • BOTH: Both text and structured data (recommended for most integrations)

Examples

Example 1: Account Summary

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

Request:

{ "response_preferences": { "include_textual_summary": true, "response_format": "BOTH" }, "content": { "text": "Give me the account summary for 26093088", "type": "QUERY" }, "metadata": { "source_agent": "agent_portal", "target_agent": "agent_billie", "source_message_id": "smi-1", "source_conversation_id": "sci-1" } }

 

Response:

{ "message_id": "msg_789", "conversation_id": "conv_456", "timestamp": "2025-02-27T01:24:05Z", "content": { "text": "Certainly, I’ll provide you with a summary of the account 26093088 for Jamie Parker. Account Details: - Account Number: 26093088 - Client Account ID: Clientaactid1345 - User ID: t6cqe65v - Full Name: Jamie Parker - Account Status: Active - Account Currency: USD Address Information: - City: California (Note: The street address is not available in the provided information) Subscription Information: - Subscription Number: 46392814 - Subscription Name: Connect 100 - Subscription Status: Active - Next Bill Date: December 4, 2024 - Last Bill Date: Not available - Bill Paid By: SELF Additional Information: - Parent Account Number: 26093088 (Same as the account number, indicating this is not a child account) - Parent Account Name: Jamie Parker This account appears to be in good standing with an active subscription. The next bill is due on December 4, 2024. The account holder is responsible for paying their own bills.", "type": "RESPONSE", "structured_data": { "response_type": "ACCOUNT_INFO", "data": { "account_number": "26093088", "client_account_id": "Clientaactid1345", "user_id": "t6cqe65v", "full_name": "Jamie Parker", "status": "Active", "currency": "USD", "address": { "city": "California" }, "subscription": { "subscription_no": "46392814", "name": "Connect 100", "status": "Active", "next_bill_date": "2024-12-04", "bill_paid_by": "SELF" }, "parent_account": { "account_no": "26093088", "name": "Jamie Parker" } }, "schema_version": "1.0" } }, "metadata": { "source_agent": "agent_billie", "target_agent": "agent_portal", "in_reply_to_message_id": "msg_123", "sequence_num": 1, "source_conversation_id": "sci-1" } }
TOP
  1. Back to top
  • Was this article helpful?

Recommended articles

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