Início Rápido

npm install @ixblix/sdk-js

import { IxblixClient } from '@ixblix/sdk-js';

const BASE_URL = 'https://api.ixblix.app';

// Integrator client — company onboarding & catalog.
export const integrator = new IxblixClient({
  baseUrl: BASE_URL,
  integratorId: process.env.IXBLIX_INTEGRATOR_ID,
  integratorAccessToken: process.env.IXBLIX_INTEGRATOR_TOKEN,
});

// Company client — conversations, messages, media, keys.
// The API key is obtained after activation (Step 5).
export const company = new IxblixClient({
  baseUrl: BASE_URL,
  apiKey: process.env.IXBLIX_API_KEY,
});

await integrator.registerIntegrator({
  name: 'My CRM Platform',
  hostname: 'mycrm.example.com',
  callbackUrl: 'https://mycrm.example.com/ixblix/callback',
});

// The callback handler on your side must answer the challenge,
// then acknowledge the credentials payload.
//   POST { type: "challenge" }  -> respond with { name, hostname, callbackUrl }
//   POST { integratorId, accessToken } -> respond 200

const { company: created, payment } = await integrator.registerCompany({
  name: 'Acme Support',
  planId: 'plan_starter',
  email: 'billing@acme.example',
  confirmationWebhookUrl: 'https://mycrm.example.com/ixblix/company-activated',
});

console.log(payment.transactionId, payment.checkoutUrl);

const { apiKey } = await integrator.activateCompany(
  created.id,
  payment.transactionId,
);

// Persist the key and build the company-scoped client.
const company = new IxblixClient({ baseUrl: BASE_URL, apiKey });

const { webhookUrl, webhookSecret } = await company.updateWebhook({
  webhookUrl: 'https://mycrm.example.com/ixblix/webhook',
});

// webhookSecret looks like: whsec_xxxxxxxx...
// Store it in your secret manager. It is never returned again.

import {
  IxblixClient,
  loadOrCreateOperatorKey,
} from '@ixblix/sdk-js';

// Load an existing keypair or create one on first run (stored with 0600 perms).
const operatorKey = loadOrCreateOperatorKey('./.ixblix-keys');

await company.registerEncryptionKey({
  keyId: operatorKey.keyId,
  publicKey: operatorKey.publicKeySpki,
});

// Build a client that can encrypt outgoing messages.
const companyWithKey = new IxblixClient({
  baseUrl: BASE_URL,
  apiKey: process.env.IXBLIX_API_KEY,
  operatorKey,
});

import express from 'express';
import { verifyWebhook, WEBHOOK_SIGNATURE_HEADER } from '@ixblix/sdk-js';

const app = express();
const webhookSecret = process.env.IXBLIX_WEBHOOK_SECRET!;

// Keep the raw body so the signature can be verified byte-for-byte.
app.post(
  '/ixblix/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.header(WEBHOOK_SIGNATURE_HEADER);
    const body = JSON.parse(req.body.toString('utf8'));

    let event;
    try {
      ({ event } = verifyWebhook(body, webhookSecret, signature));
    } catch (err) {
      return res.status(401).send('invalid signature');
    }

    switch (event.event) {
      case 'CUSTOMER_JOINED':
        return void onCustomerJoined(event);
      case 'MESSAGE_RECEIVED':
        return void onMessageReceived(event);
      case 'MESSAGE_DELIVERED':
      case 'MESSAGE_READ':
        return void onMessageRead(event);
      case 'CONVERSATION_CLOSED':
        return void onConversationClosed(event);
      case 'BALANCE_LOW':
        return void onBalanceLow(event);
      default:
        return void res.status(200).send('ok');
    }
  },
);

const { conversation, contact, deeplink } = await companyWithKey.createConversation({
  contact: {
    externalId: 'whatsapp_5511999999999',
    name: 'Jane Doe',
    metadata: { phone: '+55 11 99999-9999', ticket: 'T-1234' },
  },
  operator: {
    uuid: 'agent-42',
    name: 'Maria Silva',
    image: 'https://cdn.example.com/avatars/maria.png',
    // or: gravatarHash: md5('maria@example.com')
  },
});

// Send the deeplink back on the original channel (WhatsApp, Instagram, ...).

async function waitForCustomer(conversationId: string) {
  for (;;) {
    const keys = await companyWithKey.getConversationKeys(conversationId);
    if (keys.keyStatus === 'ACTIVE' && keys.customerPublicKey) {
      return; // customer joined — safe to call sendEncryptedMessage
    }
    await new Promise((r) => setTimeout(r, 2000));
  }
}

await waitForCustomer(conversation.id);

// Text message with operator identity embedded in the encrypted attachments.
await companyWithKey.sendEncryptedMessage(conversation.id, {
  content: 'Hello Jane! How can we help you today?',
  operatorUuid: '550e8400-e29b-41d4-a716-446655440000',
  operatorIdentity: {
    uuid: '550e8400-e29b-41d4-a716-446655440000',
    name: 'Maria Silva',
    gravatarHash: md5('maria@example.com'),
  },
});

import { decryptEnvelope } from '@ixblix/sdk-js';

const messages = await companyWithKey.listMessages(conversation.id);

for (const message of messages) {
  if (!message.contentEncrypted) continue; // system/legacy plaintext
  const plaintext = decryptEnvelope(message, operatorKey.privateKey);
  console.log(message.senderType, message.sentAt, plaintext);
}

import { readFile } from 'node:fs/promises';

// 1. Plain media (image/audio/document).
const bytes = await readFile('./invoice.pdf');
await companyWithKey.sendEncryptedMessage(conversation.id, {
  file: { data: bytes, fileName: 'invoice.pdf', mimeType: 'application/pdf' },
  operatorUuid: '550e8400-e29b-41d4-a716-446655440000',
});

// 2. Rich text message (quick replies, buttons, ...).
await companyWithKey.sendEncryptedMessage(conversation.id, {
  content: 'Your ticket is ready.',
  operatorUuid: '550e8400-e29b-41d4-a716-446655440000',
  attachments: {
    buttons: [{ type: 'reply', label: 'Open ticket', value: 'open' }],
  },
});

// 3. Media + caption + rich attachments in one call.
await companyWithKey.sendEncryptedMessage(conversation.id, {
  content: 'Here is your invoices.',
  file: { data: bytes, fileName: 'invoice.pdf', mimeType: 'application/pdf' },
  operatorUuid: '550e8400-e29b-41d4-a716-446655440000',
  attachments: {
    buttons: [{ type: 'reply', label: 'Open ticket', value: 'open' }],
  },
});

// Tell the customer you are typing / recording.
await companyWithKey.reportCompanyPresence(conversation.id, 'typing');
await companyWithKey.reportCompanyPresence(conversation.id, 'stopped');

// Mark a customer message as delivered as soon as your client receives it.
await companyWithKey.markMessageDeliveredByCompany(conversation.id, messageId);

// Mark it as read once the operator actually sees it (window focused and the
// message inside the viewport). The customer sees the receipt live.
await companyWithKey.markMessageReadByCompany(conversation.id, messageId);

// React with an emoji (encrypted to the customer, sent as contentType "react").
await companyWithKey.reactToMessage(conversation.id, messageId, '👍', '550e8400-e29b-41d4-a716-446655440000');
// Pass an empty string to clear your reaction:
// await companyWithKey.reactToMessage(conversation.id, messageId, '', '550e8400-e29b-41d4-a716-446655440000');

// Report a customer-side close/presence using the conversation token.
// (Company side uses the conversation id with its API key.)

// Erasing encrypted content is a company action:
// POST /api/conversations/{token}/erase

import {
  IxblixClient,
  loadOrCreateOperatorKey,
  decryptEnvelope,
} from '@ixblix/sdk-js';
import { createHash } from 'crypto';

const md5 = (s: string) => createHash('md5').update(s).digest('hex');
const BASE_URL = 'https://api.ixblix.app';

async function main() {
  // 1. Clients
  const integrator = new IxblixClient({
    baseUrl: BASE_URL,
    integratorId: process.env.IXBLIX_INTEGRATOR_ID,
    integratorAccessToken: process.env.IXBLIX_INTEGRATOR_TOKEN,
  });

  // 2. Register + activate a company
  const { company: created, payment } = await integrator.registerCompany({
    name: 'Acme Support',
    planId: 'plan_starter',
  });
  const { apiKey } = await integrator.activateCompany(created.id, payment.transactionId);

  // 3. Operator keypair + company client
  const operatorKey = loadOrCreateOperatorKey('./.ixblix-keys');
  const company = new IxblixClient({ baseUrl: BASE_URL, apiKey, operatorKey });

  await company.registerEncryptionKey({
    keyId: operatorKey.keyId,
    publicKey: operatorKey.publicKeySpki,
  });
  await company.updateWebhook({ webhookUrl: 'https://mycrm.example.com/ixblix/webhook' });

  // 4. Open a conversation and share the deeplink
  const { conversation, deeplink } = await company.createConversation({
    contact: { externalId: 'whatsapp_5511999999999', name: 'Jane Doe' },
    operator: { uuid: '550e8400-e29b-41d4-a716-446655440000', name: 'Maria Silva' },
  });
  console.log('Share this link:', deeplink);

  // 5. Wait for the customer, then talk
  let keys = await company.getConversationKeys(conversation.id);
  while (keys.keyStatus !== 'ACTIVE' || !keys.customerPublicKey) {
    await new Promise((r) => setTimeout(r, 2000));
    keys = await company.getConversationKeys(conversation.id);
  }

  // sendEncryptedMessage fetches keys, encrypts and sends in one call.
  await company.sendEncryptedMessage(conversation.id, {
    content: 'Hello! How can we help?',
    operatorUuid: '550e8400-e29b-41d4-a716-446655440000',
    operatorIdentity: {
      uuid: '550e8400-e29b-41d4-a716-446655440000',
      name: 'Maria Silva',
      gravatarHash: md5('maria@example.com'),
    },
  });

  // 6. Read the reply
  const messages = await company.listMessages(conversation.id);
  for (const message of messages) {
    if (message.contentEncrypted) {
      console.log(decryptEnvelope(message, operatorKey.privateKey));
    }
  }
}

main().catch(console.error);