Python SDK

What you'll buildCopy Anchor Link

A Python script that sends a message, reads incoming events, verifies webhooks and handles errors, using the voicelayer package.

Every operation in the API reference is a method on a resource class, named after it in snake case.

PrerequisitesCopy Anchor Link

• Python 3.9 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

pip install voicelayer

pip install ./voicelayer/sdks/python/voicelayer

Step 2: AuthenticateCopy Anchor Link

A Configuration holds your key; an ApiClient opens the connection. Each resource has its own class: MessagesApi, ConversationsApi, EventsApi, WebhooksApi, ChannelsApi, TestApi and LogsApi.

import os
import voicelayer

config = voicelayer.Configuration(access_token=os.environ["VOICELAYER_API_KEY"])
with voicelayer.ApiClient(config) as client:
    channels = voicelayer.ChannelsApi(client).list_channels()
    print([c.id for c in channels.channels])

The client sends Authorization: Bearer <key> to https://api.vlayers.ai. Pass host= to Configuration only if VoiceLayer gives you another host.

Step 3: Send a messageCopy Anchor Link

Request bodies are models: build one with from_dict.

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

stream_events opens the event stream, reconnects after a drop and resumes from the last cursor, so you never miss or repeat an event. Store item.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. verify_webhook checks the signature and the timestamp, then returns the parsed event:

import os
from flask import Flask, request
from voicelayer.webhooks import verify_webhook, WebhookVerificationError

app = Flask(__name__)

@app.post("/voicelayer/webhooks")
def webhook():
    try:
        event = verify_webhook(
            request.get_data(),  # the raw body, before any JSON parsing
            request.headers.get("x-voicelayer-signature"),
            os.environ["VOICELAYER_WEBHOOK_SECRET"],
        )
    except WebhookVerificationError as err:
        return err.reason, 400
    print(event["type"], event["data"])
    return "", 204

See Receive with webhooks to create the subscription.

Step 5: Handle errorsCopy Anchor Link

A refused request raises voicelayer.exceptions.ApiException (or a subclass such as BadRequestException, UnauthorizedException, ConflictException). status is the HTTP status and body is the JSON error body, with its error code, requestId, retryable and docs link.

import json
import os
import voicelayer
from voicelayer.exceptions import ApiException

config = voicelayer.Configuration(access_token=os.environ["VOICELAYER_API_KEY"])
with voicelayer.ApiClient(config) as client:
    try:
        voicelayer.MessagesApi(client).send_message(
            send_message_request=voicelayer.SendMessageRequest.from_dict(
                {"channel": "sms", "to": "+15550123", "content": {"type": "text", "text": "Hello"}}
            ),
        )
    except ApiException as err:
        body = json.loads(err.body) if err.body else {}
        print(err.status, body.get("error"), body.get("message"))
        print("retryable:", body.get("retryable"), "request:", body.get("requestId"), "docs:", body.get("docs"))

Retry when retryable is true, 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, pass 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."
    }
  }'

Step 6: Page through listsCopy Anchor Link

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

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

next_cursor 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 classes above are the whole client today. A shorter one, VoiceLayer() with vl.messages.send(channel=..., to=..., text=...), ships in the first release of voicelayer, and these classes 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.
• Python framework packages for Claude, OpenAI Agents and LangGraph.