Web Integrations

Official npm packages for sending and receiving Twilic payloads over HTTP and WebSocket. All packages share the same codec interface and @twilic/core dependency.

Content type

application/vnd.twilic

Every package exports TWILIC_CONTENT_TYPE. Set this header on Twilic HTTP request and response bodies. WebSocket framing uses binary opcode instead of HTTP headers.

Package overview

Package	Role	Reference
@twilic/hono	Hono server middleware	Hono
@twilic/express	Express middleware	Express
@twilic/fastify	Fastify plugin	Fastify
@twilic/fetch	fetch client	Fetch
@twilic/axios	Axios client	Axios
@twilic/websocket	WebSocket frames	WebSocket

Shared codec interface

All integrations accept an optional custom codec:

interface TwilicCodec {
  encode: (value: TwilicValue) => Uint8Array;
  decode: (bytes: Uint8Array) => TwilicValue;
}

Use createTwilicHono(codec), createTwilicFetch(codec), or createTwilicWebSocket(socket, { codec }) when you need batch encoding, a session encoder, or a wrapped @twilic/core/advanced encoder.

HTTP profile rules

Profile	HTTP-safe?	Notes
Dynamic (stateless)	Yes	Single object bodies
Batch	Yes	List endpoints, bulk export
Bound (schema)	Yes	Fixed message types
Stateful (session)	No	Requires ordered persistent channel

Use stateless profiles for request/response. Reserve stateful encoding for WebSocket or streaming connections — see @twilic/websocket. See FAQ — HTTP.

Server setup pattern

// 1. Initialize core once at startup
import { init } from "@twilic/core";
await init();

// 2. Register Twilic routes separately from JSON routes
app.post("/internal/data", twilicParser(), handler);

// 3. Do not mount JSON body parser on the same path

Client setup pattern

import { init } from "@twilic/core";
import { twilicFetchJson } from "@twilic/fetch";

await init();

const data = await twilicFetchJson("/api/users", {
  method: "GET",
  headers: { Accept: "application/vnd.twilic" },
});

Content negotiation

Serve both JSON and Twilic on the same route with Accept header routing:

app.get("/users", async (req, res) => {
  const users = await fetchUsers();
  if (req.headers.accept?.includes("application/vnd.twilic")) {
    return twilicSend(res, users);
  }
  return res.json(users);
});

The examples repository includes:

• api-response — Batch GET size comparison
• http-roundtrip — Express / Hono / Fastify + fetch / Axios POST echo
• websocket-session — Stateful stream with @twilic/websocket

See Examples — HTTP Round-Trip and Examples — WebSocket Session.

Related

• Transport & Framing
• JavaScript Core API
• Web Integrations guide
• Twilic AI — LLM / agent session recording (separate from HTTP adapters)