Lobstercom
Integration Guide

Lobstercom for OpenClaw

Give your OpenClaw agent a real phone number. Receive SMS, MMS, and voice calls directly in your OpenClaw conversations.

3-step setupSMS + MMS supportVoice coming soon

Introduction

Give your OpenClaw agent a real phone number. Receive SMS, MMS, and voice calls directly in your OpenClaw conversations.

Lobstercom acts as a phone carrier for AI agents. This guide walks you through connecting your OpenClaw instance to Lobstercom so your agent can communicate with the real world over SMS and MMS.

Prerequisites

Before you begin, make sure you have the following:

  • A Lobstercom accountCreate account
  • An active phone number on Lobstercom-- Provision one from the dashboard
  • An API key for your phone number-- Generated in your number's API Key tab
  • A running OpenClaw instanceGitHub

Quick Setup

1

Get your Lobstercom API key

  1. Log in to the Lobstercom dashboard
  2. Navigate to your phone number and open the API Key tab
  3. Click "Generate API Key" and copy it immediately
Important: The API key is only shown once. Store it securely before closing the dialog.
2

Install the Lobstercom channel

Copy the agent-phone extension into your OpenClaw extensions/ directory:

Terminalbash
# From the OpenClaw root directory
cp -r path/to/agent-phone extensions/agent-phone
Note: Once the Lobstercom channel is merged into OpenClaw core, this step will no longer be necessary -- it will be built-in.
3

Configure in OpenClaw

Add the Lobstercom channel to your OpenClaw configuration file (.openclaw/config.yaml or equivalent):

Configyaml
channels:
  agentPhone:
    accounts:
      default:
        apiKey: "ap_your_api_key_here"
        phoneNumberId: "your-phone-number-uuid"
        agentPhoneUrl: "https://lobstercom.ai"

Replace ap_your_api_key_here with your actual API key and your-phone-number-uuid with the UUID from your dashboard.

How It Works

Here is the full message lifecycle when someone texts your Lobstercom number:

1

Someone texts your number

2

Lobstercom receives the message

3

Forwarded to OpenClaw webhook

4

OpenClaw processes with AI

5

Reply sent via Lobstercom API

6

Person receives SMS reply

Message Format

When an inbound message arrives, Lobstercom formats it and forwards it to your OpenClaw instance. Here is the payload your agent receives:

Inbound Message Payloadjson
{
  "event": "message.inbound",
  "channel": "sms",
  "from": "+15551234567",
  "to": "+15559876543",
  "body": "Hello agent",
  "media": [],
  "timestamp": "2026-02-24T12:00:00Z",
  "message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
FieldTypeDescription
eventstringEvent type. Currently "message.inbound".
channelstring"sms" for text messages.
fromstringE.164 phone number of the sender.
tostringYour Lobstercom number that received the message.
bodystringThe text content of the message.
mediastring[]Array of media URLs for MMS attachments. Empty for plain SMS.
timestampstringISO 8601 timestamp of when the message was received.
message_idstringUnique identifier for this message.

Features

SMS in/out

Send and receive text messages through your agent

MMS in/out

Support for images, videos, and other media attachments

Webhook signature verification

HMAC-SHA256 signatures on every inbound webhook

Auto-retry on webhook failure

3 automatic retry attempts with exponential backoff

Usage tracking and billing

Per-number message volume and cost tracking

Contact rules

Allow/block lists to control who can message your agent

SoonVoice calls

Real-time voice conversations with your AI agent

Configuration Reference

Full list of configuration options for the Lobstercom channel in your OpenClaw config:

OptionRequiredDefaultDescription
apiKeyYes--Your Lobstercom API key (starts with ap_)
phoneNumberIdYes--UUID of your phone number
agentPhoneUrlNohttps://lobstercom.aiLobstercom instance URL
enabledNotrueEnable/disable the channel
nameNo"default"Account display name
allowFromNo[]Phone numbers allowed to message (empty = allow all)
dmPolicyNo"open""open" or "pairing" -- controls who can initiate conversations

API Endpoints

These are the Lobstercom API endpoints used by the OpenClaw channel integration:

POST/api/numbers/:id/connectConfigure webhook URL for inbound message forwarding. Called during initial setup.
GET/api/numbers/:id/connect/statusCheck connection health and webhook delivery status.
POST/api/numbers/:id/send/smsSend outbound SMS/MMS messages from your phone number.
POST/api/twilio/sms/:numberIdReceives inbound messages from carrier (internal -- not called by your agent).
Tip: For full API documentation including request/response schemas, visit the API Reference.

Troubleshooting

Common issues and their solutions:

"Invalid API key"

Your API key may have been revoked or mistyped. Go to your phone number's API Key tab in the dashboard and generate a new one.

"Webhook unhealthy"

Ensure your OpenClaw instance is publicly accessible from the internet. Lobstercom needs to reach your webhook URL to deliver messages.

"Messages not arriving"

Check that your contact rules are not blocking the sender. Also verify the phone number is active and your subscription is current.

"Connection refused"

Verify that the agentPhoneUrl in your config is correct. The default is https://lobstercom.ai.

"Timeout errors"

Your OpenClaw agent must respond within the webhook timeout (default 10s). For longer processing, return {"action":"ignore"} and reply asynchronously via the send API.