Lobstercom
Get Started
Docs/Getting Started

Getting Started

Everything you need to know before integrating Lobstercom with your AI agent. This guide covers prerequisites, integration options, and what to expect.

Overview

Lobstercom is a phone carrier built for AI agents. It gives your agent its own real phone number capable of sending and receiving SMS, MMS, and voice calls. People text or call your agent's number just like any other phone number, and your agent handles the conversation.

Unlike traditional telephony APIs that require you to manage SIP trunks, PSTN routing, and carrier relationships, Lobstercom abstracts all of that away. You configure a webhook URL, and we forward messages to your agent as simple JSON. Your agent responds inline or calls our API to send messages later.

SMS & MMS

Send and receive text messages and media. Your agent gets a real phone number that works with any handset.

Voice

Inbound and outbound voice calls with real-time streaming. Connect your agent to live phone conversations.

AI APIs

Optional hosted STT, TTS, and LLM endpoints. OpenAI-compatible, so your existing SDK code just works.

Prerequisites — What You Need

To integrate with Lobstercom, you need two things:

1

An AI agent or application that can receive HTTP webhooks

Your agent needs a server or endpoint that accepts incoming HTTP POST requests with a JSON body. This is how Lobstercom delivers inbound messages to your agent.

2

A publicly accessible webhook URL

The endpoint must be reachable from the internet. This can be a cloud server, a serverless function, an ngrok tunnel during development, or any publicly routable URL.

That's it for basic SMS integration. No special SDKs, no binary protocols, no SIP configuration. If your agent can handle an HTTP POST and return JSON, it can use Lobstercom.

Integration Options

There are two ways to connect your agent to Lobstercom. Choose the path that fits your setup.

Option A

Webhook Integration

Most Common

Connect any AI agent directly by configuring a webhook URL. Lobstercom forwards inbound messages to your endpoint and your agent responds.

1Sign up at lobstercom.ai
2Subscribe ($29/month per number)
3Provision a phone number from the dashboard
4Configure your webhook URL in the dashboard
5Lobstercom forwards inbound SMS/MMS to your webhook as JSON
6Your webhook responds inline, or use the API to send messages later
You need: a server or endpoint that accepts POST requests with a JSON body and returns JSON responses within 10 seconds.
Option B

OpenClaw Integration

If you're using OpenClaw, Lobstercom is available as a channel plugin. No webhook setup needed — OpenClaw handles the integration for you.

1Install the Lobstercom channel in your OpenClaw agent
2Connect your Lobstercom account through the OAuth flow
3Your OpenClaw agent automatically receives and sends messages
No webhook setup needed. OpenClaw manages the connection between your agent and Lobstercom automatically.

See the OpenClaw integration guide for detailed setup instructions.

What Your Webhook Receives

When someone texts your Lobstercom number, we send a POST request to your webhook URL with a JSON payload.

Inbound Webhook Payload (POST)
{
  "event": "message.inbound",
  "from": "+15551234567",
  "to": "+15559876543",
  "body": "Hello agent",
  "channel": "sms",
  "media": [],
  "timestamp": "2026-02-24T15:30:00.000Z",
  "message_id": "msg_a1b2c3d4"
}

See the full webhook payload reference for all fields, including signature verification.

What Your Webhook Returns

Your webhook responds with JSON telling Lobstercom what to do. You have up to 10 seconds to respond.

Reply to the Sender
{
  "reply": "Hi! How can I help?",
  "action": "respond"
}
Acknowledge Without Replying
{
  "action": "ignore"
}
Tip: If your agent needs more processing time, return {"action":"ignore"} immediately, then use the POST /api/numbers/:id/send/sms endpoint to reply asynchronously when ready.

See the full response reference for all available fields and actions.

Optional: Voice AI APIs

If your agent needs speech-to-text, text-to-speech, or LLM capabilities, Lobstercom provides hosted APIs.

Lobstercom hosts OpenAI-compatible APIs for STT, TTS, and chat completions at $0.03/min. Point your existing OpenAI SDK at our base URL and you're set — no code changes beyond the URL and API key.

Python Example
from openai import OpenAI

client = OpenAI(
    api_key="agp_your_api_key_here",
    base_url="https://lobstercom.ai/api/v1"
)

# Speech-to-text, text-to-speech, and chat completions
# all work with the standard OpenAI SDK methods.

Speech-to-Text

Fast, accurate transcription. Supports wav, mp3, webm, and more.

Text-to-Speech

24 natural voices. Returns wav audio.

Chat Completions

Qwen3-Next-80B with streaming support.

See the Voice AI API documentation for full endpoint details and code examples.

Quick Checklist

Use this checklist to make sure you have everything ready before going live.

  • Your Agent

    • Webhook URL ready (publicly accessible)
    • Can accept POST requests with JSON body
    • Can return JSON responses within 10 seconds

  • Lobstercom

    • Lobstercom account created at lobstercom.ai
    • Subscription active ($29/month)
    • Phone number provisioned from the dashboard
    • Webhook URL configured in the dashboard

Next Steps

API Documentation

Full reference for all endpoints, webhook payloads, authentication, and Voice AI APIs.

OpenClaw Integration

Step-by-step guide for connecting Lobstercom as a channel in your OpenClaw agent.

Dashboard

Manage your phone numbers, configure webhooks, generate API keys, and monitor usage.