Private App: Connecting custom CX platforms

The Private App integration lets you connect any CX platform that isn't natively supported by Engaige. Your system sends conversations and messages to Engaige via a REST API; Engaige processes them with your AI Agent and sends the results back to a webhook endpoint you configure.

For the full API reference, see the interactive docs at api.letsengaige.com/v3/docs.

Step 1: Create the integration

1. Go to Settings > Integrations and click + Private App.

2. Fill in:

   • Name: a label for this integration (e.g. "My CRM Webhook")

   • Webhook URL: the endpoint on your server where Engaige will POST events (e.g. https://api.example.com/webhooks/engaige)

   • Engaige agent ID (optional): the ID your system uses for Engaige's bot user, to filter out messages sent by Engaige and prevent processing loops

   • Runtime resources: list of queues or teams in your system that conversations can be routed to. Each resource needs an external ID and a display name. You can assign your agent to one of these resources as its default queue, and you can select them as the handover target — the chosen resource's external ID will be included in the conversation.transferred webhook event.

3. Save. A signing_secret is displayed once. Copy and store it securely; it cannot be retrieved again. You will use it to verify that incoming webhooks are genuinely from Engaige.

Step 2: Get an API credential

The inbound API uses Bearer token authentication. Go to Settings > Credentials, create an API credential, and include it in every inbound request:

Authorization: Bearer your_api_credential

Inbound API: pushing data to Engaige

Use the inbound API to create conversations and add messages (customer or employee) to Engaige. All endpoints are under https://api.letsengaige.com/v3/integrations/private_app/{integration_id}. For full request schemas and examples, see the API reference → Private App Conversations.

A few things to keep in mind:

• Create the conversation before sending any messages. The external_id is your system's ticket or conversation ID.

• The external_resource_id must match one of the external IDs configured in your Private App's runtime resources.

• Adding a customer message triggers AI processing. Adding an employee message gives the AI context but does not trigger processing.

• Include a unique idempotency_key on every message so retries are safe.

Outbound webhooks: events Engaige sends to you

Engaige POSTs events to your configured webhook URL. For the full list of event types and payload schemas, see the API reference → Private App Outbound Webhooks.

Verifying webhook signatures

Each outbound webhook includes two headers:

• X-Engaige-Signature: HMAC-SHA256 signature in hex format

• X-Engaige-Timestamp: Unix timestamp in seconds

To verify a webhook: compute hex(hmac_sha256(signing_secret, timestamp + "." + raw_body)) and compare it to the X-Engaige-Signature header. Always validate the timestamp to prevent replay attacks.