TypeScript SDK

What you'll buildCopy Anchor Link

A Node.js script that sends a message, reads incoming events, verifies webhooks and handles errors, using @voicelayer/api.

Every operation in the API reference is a typed function named after it.

PrerequisitesCopy Anchor Link

• Node.js 18 or later.
• A secret API key in VOICELAYER_API_KEY. Use a test key (vl_test_…) while you build: see Authentication and API keys.
• No phone number needed: with a test key, your workspace's free test sender stands in for one.

Step 1: InstallCopy Anchor Link

npm install @voicelayer/api

Step 2: AuthenticateCopy Anchor Link

Create one client and pass it to every call. With throwOnError: true, a refused request throws instead of returning an error field.

import { createVoiceLayerClient } from '@voicelayer/api';

const client = createVoiceLayerClient({ apiKey: process.env.VOICELAYER_API_KEY!, throwOnError: true });

The client sends Authorization: Bearer <key> to https://api.vlayers.ai. The package is an ES module and the examples use top-level await: in a new project, run npm pkg set type=module once, then run a file with npx tsx example.ts.

Step 3: Send a messageCopy Anchor Link

Each function takes { client, path, query, headers, body }, as the operation needs.

curl -X POST https://api.vlayers.ai/v1/messages \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+15550123",
    "content": {
      "type": "text",
      "text": "Your table for two is booked for 7pm."
    }
  }'

You get 202 Accepted with the queued message:

{
  "message": {
    "id": "0192f5b0-8d1f-7b62-8c3e-5f9a2b7d4e32",
    "conversationId": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",
    "channel": "sms",
    "direction": "outbound",
    "status": "queued",
    "text": "Your table for two is booked for 7pm.",
    "media": [],
    "from": "+14155550100",
    "to": "+15550123",
    "bindingId": null,
    "metadata": {},
    "error": null,
    "createdAt": "2026-10-20T15:04:05.000Z",
    "parts": [
      {
        "id": "0192f5b0-8d1f-7b62-8c3e-5f9a2b7d4e32",
        "status": "queued"
      }
    ]
  }
}

Step 4: Receive messagesCopy Anchor Link

streamEvents opens the event stream, reconnects after a drop and resumes from the last cursor, so you never miss or repeat an event. Store cursor after you handle each event.

curl -N "https://api.vlayers.ai/v1/events/stream?types=message.*" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Accept: text/event-stream"

To receive webhooks instead, verify each delivery against the raw request body before you parse it. verifyWebhook checks the signature and the timestamp, then returns the parsed event:

import { verifyWebhook, WebhookVerificationError } from '@voicelayer/api';

export async function POST(request: Request) {
  const payload = await request.text(); // the raw body, before any JSON parsing
  try {
    const event = verifyWebhook({
      payload,
      headers: request.headers,
      secret: process.env.VOICELAYER_WEBHOOK_SECRET!
    });
    console.log(event.type, event.data);
    return new Response(null, { status: 204 });
  } catch (err) {
    if (err instanceof WebhookVerificationError) return new Response(err.reason, { status: 400 });
    throw err;
  }
}

See Receive with webhooks to create the subscription.

Step 5: Handle errorsCopy Anchor Link

A refusal throws VoiceLayerApiError. Read code to decide what to do, and quote requestId if you contact support.

import { createVoiceLayerClient, sendMessage, VoiceLayerApiError } from '@voicelayer/api';

const client = createVoiceLayerClient({ apiKey: process.env.VOICELAYER_API_KEY!, throwOnError: true });

try {
  await sendMessage({
    client,
    body: { channel: 'sms', to: '+15550123', content: { type: 'text', text: 'Hello' } }
  });
} catch (err) {
  if (err instanceof VoiceLayerApiError) {
    console.error(err.status, err.code, err.message);
    console.error('retryable:', err.retryable, 'request:', err.requestId, 'docs:', err.docs);
  } else {
    throw err; // a network failure: retry with the same idempotency key
  }
}

retryable is true for a rate limit or a temporary failure. Retry those with backoff and the same idempotency-key. Fix the request for anything else. See Errors, retries and idempotency.

To make a send safe to retry, add an idempotency-key. A retry with the same key never sends twice:

curl -X POST https://api.vlayers.ai/v1/messages \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "channel": "sms",
    "to": "+15550123",
    "content": {
      "type": "text",
      "text": "Your table for two is booked for 7pm."
    }
  }'

Use another host only if VoiceLayer gives you one: createVoiceLayerClient({ apiKey, baseUrl: 'https://api.example.com' }).

Step 6: Page through listsCopy Anchor Link

List calls return a cursor. To read a conversation's history newest first, ask for before: 'end', then pass each page's prevCursor back as before:

curl "https://api.vlayers.ai/v1/conversations/$CONVERSATION_ID/messages?before=end&limit=20" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"

nextCursor works the same way forward with after. See Pagination.

Test itCopy Anchor Link

With a test key, simulate a person texting you from a reserved number, then reply in the conversation it opens. Nothing reaches a real carrier and it costs nothing.

curl -X POST https://api.vlayers.ai/v1/test/inbound \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "from": "+15550123",
    "text": "Do you have a table for two tonight?"
  }'

Save the printed id as CONVERSATION_ID, then reply:

curl -X POST "https://api.vlayers.ai/v1/conversations/$CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": {
      "type": "text",
      "text": "Yes, we have a table at 7pm. Shall I book it?"
    }
  }'

See Test mode.

Advanced: the generated clientCopy Anchor Link

The functions above are the whole client today. A shorter one, new VoiceLayer() with voicelayer.messages.send({ channel, to, text }), arrives in the next @voicelayer/api release, and these functions keep working after it.

Common errorsCopy Anchor Link

Method referenceCopy Anchor Link

Every call in the SDK, by resource. Each links to its full reference page with parameters and examples.

Next stepsCopy Anchor Link

• Receive with webhooks or the event stream.
• Hand off a conversation between your code, your agent and people.
• Direct mode: answer messages with a handler instead of a loop.