API and integration overview

Commerce API v1 is the public API through which your store sends commerce data (catalog, customers, orders, and repurchase intents), and CallBotAgent turns it into phone conversations and returns structured results. This section describes the integration contract: data formats, authentication, error handling, limits, and webhooks.

The base URL for all resources is:

https://api.callbotagent.ai/api/v1/commerce

Who this API is for

This documentation is intended for developers integrating a store (a custom e-commerce backend or a platform without a ready-made connector) with CallBotAgent. We assume you work server-side and can securely store the key secret — request signing never happens in the browser or in a customer mobile app.

If you use a ready-made connector, you can configure most of the integration without code — see Custom store / API connector.

How store data becomes conversations

The end-to-end flow looks like this:

1. Catalog and customer sync — you send products, variants, and customer data so the bot has conversation context.
2. Commerce event — you pass an order or a repurchase intent that qualifies the contact for a conversation.
3. Conversation — CallBotAgent places a call according to sales rules and contact consent.
4. Result — you receive a structured conversation outcome via webhook (push) or by polling the results resource.

Documentation map

• API Console in the dashboard — /dashboard/developer mockup (keys, playground, requests, webhooks) with screenshots.
• Key generation and rotation — create → reveal-once → rotate / revoke.
• Quick start — from key creation to the first result in four steps.
• Authentication — HMAC, key ID, signature headers, scopes, and key rotation.
• Idempotency — safe mutation retries, source_version.
• Errors — Problem Details format and the full code list.
• Pagination and limits — cursor pagination, payload limits, and rate limits.
• Webhooks — receiving and verifying push events.
• Security and data — secret protection, TLS, consent, and DNC.

Contract rules

All resources share the same format conventions. Follow them to avoid validation errors.

Always pass amounts as text, not floating-point numbers — this prevents rounding errors. Currency and amount are always provided together.

The v1 contract is versioned in the path (/v1/). Breaking changes will go to a new version; within v1 we add only backward-compatible extensions (new, optional fields). Ignore unknown fields in responses instead of treating them as errors.