Billie Connect API
Overview
The Billie Connect Converse API provides third-party systems with programmatic access to Billie. This API enables external applications/Agents to integrate conversational AI capabilities for customer support, billing inquiries, and account management.
The API implements OAuth 2.0 client credential flow for secure authentication and supports both synchronous (v2) and asynchronous webhook-based (v3) interaction patterns.
Overview of Billie Connect Converse API
Core Capabilities
- Customer service chat interactions
- Account and billing inquiries
- Invoice information retrieval
- Subscription management
- Service credit applications
- Plan recommendations
Architecture Overview
Billie Connect exposes two main API versions through AWS API Gateway:
- v2 Converse API (/v2/converse): Synchronous request-response API
- v3 Converse API (/v3/converse): Asynchronous webhook-based API
Learn more details regarding differences between V2 and V3.
Both APIs leverage:
- AWS Bedrock with Claude Sonnet 4.5 and Claude Haiku 4.5 for AI processing
- Multi-agent architecture for intent classification and response generation
- Real-time chat capabilities with conversation history management
- Secure authentication using OAuth 2.0 client credential flow
- Billie Connect Converse API Prerequisites
- Before using the Billie Connect Converse API, you must implement OAuth 2.0 client credentials with JWT token handling. You also need a valid client number and a Billie service account, and for v3, a public HTTPS webhook endpoint.
- Service Accounts for Billie Connect
- Billie Connect uses a service account's assigned role to set the permissions it operates within. The service account authenticates through OAuth 2.0 client credentials rather than a password, and Aria enforces access control by matching the token's client and account numbers against the request.
- Version 2 vs. Version 3 of Billie Converse API and API Endpoints
- Billie Connect offers two API versions: v2 returns an immediate synchronous response, while v3 processes requests asynchronously and delivers the response through a webhook callback. You choose v2 for real-time interactive applications and v3 for higher-volume backend integrations.
- Billie Connect Converse API V2 Specification
- This article gives the full API specification for Billie Connect Converse V2, the synchronous conversational endpoint. It documents the request and response data models, and lists the structured response types the API can return, such as invoice, billing estimate, and contract information.
- Billie Connect Converse API V3 Specification
- This article gives the request and response format for Billie Connect Converse API v3, the asynchronous webhook-based endpoint. It explains the required callback URL, the webhook delivery structure, and the security and implementation requirements for the receiving endpoint.
- Obtaining a Bearer Token
- This article explains how to request a bearer token using the OAuth 2.0 client credential flow for Billie Connect. It shows the token request and response format, the JWT claim structure, a sample implementation, and the OAuth endpoints for each region and environment.
- Authentication Flow Diagrams
- This article shows how a third-party system can use existing Aria Core APIs and the client credential flow to communicate with Billie Connect. It addresses how such a system responds to end-user inquiries through this authentication approach.