Vendor integration workflow

Prepare the integration

1. Configure your application name/logo, allowed origins and exact callback URLs in API Vendor.
2. Create a vendor credential and keep it in your backend secret store.
3. Use your application’s authenticated customer session as the starting point for Connect MonCha.
4. Generate a random state value and PKCE verifier/challenge; retain them in that same server-side session.

Connect, create, train and install

The enterprise tenant ID belongs in backend authentication. The customer tenant ID belongs in the returned bot’s widget installation. Mixing them targets the wrong context.

1. Create a connection session through /vendor/v1/connect/sessions.
2. Open the returned authorization URL and let the customer approve access in MonCha.
3. Validate callback state and exchange the code with the stored PKCE verifier.
4. Store the resulting connection ID against the same local customer.
5. Create the bot for that connection using an available enterprise tier and a stable Idempotency-Key.
6. Submit knowledge and poll the returned training status until processing completes or reports a failure.
7. Install using the customer tenant ID and bot ID returned by the API.

Retry safely and recover

• Retry a transient failure with the same idempotency key and identical body for an idempotent operation.
• Do not reuse the key for a different bot or ingestion payload.
• For a consent/scope error, review the customer grant rather than retrying unchanged.
• For exhausted capacity, free or allocate a slot in the requested tier.
• For partial training failures, inspect document-level results instead of assuming the whole submission is ready.
• Rotate the vendor secret in your backend and revoke the old key after the replacement is working.

• Full Vendor contract, schemas and examples