Billie Connect Converse API V2 Specification

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

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

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