REST API Reference

Every endpoint exposed by the ixblix public API. Base URL: https://api.ixblix.app. All paths are prefixed with /api. Responses are JSON. Errors follow the standard error format.

Table of contents

• Integrators
• Companies — onboarding
• Companies — profile & customization
• Encryption keys
• Conversations
• Messages
• Media
• Contacts
• Payments & credits
• Plans
• Key transfer
• Webhooks relay
• Installation

Integrators

Register a new integrator platform. Three-way handshake via callbackUrl.

// Request
{
  "name": "My CRM",
  "hostname": "mycrm.example.com",
  "callbackUrl": "https://mycrm.example.com/ixblix/callback",
  "force": false,
  "subscriptionId": "asaas:sub_xxx"
}

// Response 200
{ "success": true, "message": "Registration challenge sent" }

Fetch the authenticated integrator's profile.

Companies — onboarding

Register a company (keyless). Returns payment instructions.

// Request
{
  "name": "Acme Support",
  "planId": "plan_starter",
  "email": "billing@acme.example",
  "taxId": "12345678000199",
  "confirmationWebhookUrl": "https://mycrm.example.com/ixblix/activated"
}

// Response 200
{
  "company": { "id": "...", "name": "...", "status": "PENDING_PAYMENT" },
  "payment": {
    "transactionId": "txn_xxx",
    "provider": "asaas",
    "amountCents": 4990,
    "currency": "BRL",
    "confirmationUrl": "...",
    "checkoutUrl": "https://checkout.asaas.com/...",
    "status": "PENDING"
  }
}

Activate a company after payment confirmation. Returns the API key.

// Response 200
{ "apiKey": "smci_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "status": "ACTIVE" }

Fetch payment status for a transaction. Safe — the transactionId is in the URL.

List all companies under the authenticated integrator.

Companies — profile & customization

Fetch the authenticated company's profile, including white-label customization.

// Response 200
{
  "id": "...",
  "name": "Acme Support",
  "status": "ACTIVE",
  "websiteUrl": "https://acme.example",
  "customizations": {
    "id": "...",
    "brandName": "Acme",
    "logoUrl": "...",
    "rectangularLogoUrl": "...",
    "squareIconUrl": "...",
    "primaryColor": "#2563eb",
    "faviconUrl": "...",
    "websiteUrl": "https://acme.example",
    "welcomeMessage": "Hello! How can we help?"
  }
}

Fetch the company's prepaid balance and plan state.

Update white-label customization (brand name, logos, colors, welcome message).

Upload branding assets (square icon and/or rectangular logo) as multipart/form-data.

Set or rotate the webhook endpoint. Returns the HMAC secret once.

// Request
{ "webhookUrl": "https://mycrm.example.com/ixblix/webhook", "rotateSecret": true }

// Response 200
{ "webhookUrl": "...", "webhookSecret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }

Update company configuration (name, website URL, etc.).

Fetch a company's public profile by ID (used by the customer web app).

Encryption keys

Register or rotate the company's RSA public key for E2EE.

// Request
{ "keyId": "xxxxxxxxxxxxxxxx", "publicKey": "base64-spki-der..." }

// Response 200
{
  "id": "...",
  "keyId": "xxxxxxxxxxxxxxxx",
  "publicKey": "...",
  "status": "ACTIVE",
  "activatedAt": "...",
  "retiredAt": null,
  "createdAt": "..."
}

Fetch the currently active company encryption key.

Conversations

Create an overflow conversation for a contact. Returns a deeplink to share.

// Request
{
  "contact": {
    "externalId": "whatsapp_5511999999999",
    "name": "Jane Doe",
    "metadata": { "phone": "+55 11 99999-9999" }
  },
  "operator": {
    "uuid": "agent-42",
    "name": "Maria Silva",
    "image": "https://cdn.example.com/avatars/maria.png"
  }
}

// Response 200
{
  "conversation": { "id": "...", "token": "...", "status": "ACTIVE", "keyStatus": "AWAITING_CUSTOMER", "createdAt": "..." },
  "contact": { "id": "...", "externalId": "...", "name": "Jane Doe", "consentStatus": "PENDING" },
  "deeplink": "https://app.ixblix.app/c/...",
  "company": { "id": "...", "name": "Acme", "customizations": { "brandName": "..." } },
  "operator": { "uuid": "agent-42", "name": "Maria Silva" }
}

List conversations by customer public key (used during key transfer).

Fetch a conversation by its token (customer-facing).

Close a conversation (customer-side).

Register the customer's public key (called when the customer opens the deeplink).

Erase the encrypted content of a conversation (LGPD/data retention).

Unified presence route. With X-API-Key (ref = conversation id), emits a Socket.io presence event to the customer. Without API key (ref = deeplink token), emits a TYPING/RECORDING/CHAT_CLOSED webhook to the operator.

Fetch the E2EE key state of a conversation (operator view).

Update the operator identity attached to a conversation.

Messages

Send an encrypted message from the company to the contact. The operator identity (name, image, gravatarHash) is embedded in the encrypted attachments JSON as { "operator": { ... } } so the customer client can render the correct avatar per message.

// Request
{
  "conversationId": "...",
  "content": "base64-ciphertext...",
  "contentType": "text",
  "iv": "base64-iv",
  "authTag": "base64-auth-tag",
  "encryptedKey": "base64-wrapped-key",
  "selfEncryptedKey": "base64-wrapped-key",
  "keyId": "xxxxxxxxxxxxxxxx",
  "operatorUuid": "550e8400-e29b-41d4-a716-446655440000",
  "replyToId": "...",
  "attachments": "encrypted-json-blob"
}

// Response 200
{ "id": "...", "conversationId": "...", "senderType": "COMPANY", "content": "...", "contentEncrypted": true }

Send an encrypted message from the contact to the company.

Marca uma mensagem enviada pelo contato como entregue ao operador. Emite o evento Socket.io message_delivered. Sem efeito quando a mensagem já foi lida.

Marca uma mensagem enviada pelo contato como lida pelo operador. Emite o evento Socket.io message_read. Só reporte leitura quando a janela estiver em foco e a mensagem estiver na viewport.

Marca uma mensagem enviada pela empresa como entregue ao contato. Emite o webhook MESSAGE_DELIVERED. Sem efeito quando a mensagem já foi lida.

Marca uma mensagem enviada pela empresa como lida pelo contato. Emite o webhook MESSAGE_READ. Só é reportado quando a janela está em foco e a mensagem está na viewport.

List all messages of a conversation (content is always ciphertext when encrypted).

Media

Upload encrypted media from the company (multipart/form-data).

curl -X POST https://api.ixblix.app/api/media/company \
  -H "X-API-Key: smci_xxxx" \
  -F "conversationId=..." \
  -F "file=@invoice.pdf" \
  -F "iv=..." \
  -F "authTag=..." \
  -F "encryptedKey=..." \
  -F "selfEncryptedKey=..." \
  -F "keyId=..." \
  -F "operatorUuid=550e8400-e29b-41d4-a716-446655440000"

Upload encrypted media from the contact.

Fetch media metadata (envelope + file info).

Fetch media metadata (customer-facing).

Download the raw encrypted bytes of a media file.

Download the raw encrypted bytes (customer-facing).

Contacts

Fetch a contact by conversation token.

Update the contact's consent status (LGPD).

// Request
{ "consentStatus": "GRANTED" }

// Response 200
{ "id": "...", "externalId": "...", "consentStatus": "GRANTED", "consentedAt": "..." }

Payments & credits

List available payment providers.

Fetch available payment instruments for a checkout.

Pay a checkout with a credit card.

Pay a checkout with Pix Automático.

Fetch the status of a checkout transaction.

Gateway callback endpoint. Mounted with express.raw for signature verification.

Purchase prepaid credits for the authenticated company.

List the company's credit purchases.

Start a payment method setup flow (e.g. add a card).

Register a payment method after setup.

List stored payment methods (default first).

Set a payment method as the default.

Delete a payment method.

Fetch available payment instruments for re-subscribing or switching methods.

Start a payment change checkout. Returns a hosted checkout URL.

Plans

List all active subscription plans.

// Response 200
[
  {
    "id": "plan_starter",
    "name": "Starter",
    "description": "Up to 100 conversations/month",
    "billingType": "CONVERSATIONS",
    "includedConversations": 100,
    "includedMessages": null,
    "durationDays": 30,
    "priceCents": 4990,
    "overagePriceCents": 50,
    "isActive": true,
    "isPublic": true,
    "createdAt": "..."
  }
]

Key transfer

Key transfer allows a customer to migrate their encryption key to a new device. The flow is unauthenticated and rate-limited.

Create a new key transfer request.

Fetch a key transfer request.

Delete a key transfer request.

Confirm a key transfer (customer approves on the new device).

Fetch the status of a key transfer.

Webhooks relay

Relay a message from the original channel (WhatsApp, Instagram, etc.) into ixblix.

// Request
{
  "conversationId": "...",
  "content": "base64-ciphertext",
  "iv": "...",
  "authTag": "...",
  "encryptedKey": "...",
  "selfEncryptedKey": "...",
  "keyId": "...",
  "metadata": { "channelMessageId": "..." }
}

Installation

Fetch the installation configuration (used by the customer web app to discover the API).

Interactive documentation

The full OpenAPI spec is served at ixblix.app/pt/docs/api with interactive try-it-out. The spec auto-detects the browser language (English, Portuguese, Spanish).