← Olly Messenger

Documentation

Getting started with the Olly Messenger API.

Credentials

Before using the API you must obtain your account's API Key manually by contacting us at [email protected].

API Endpoints

Sending Messages & Attachments

You can send a message by using the content field, or an attachment by including the url field pointing to a publicly accessible file URL.

Messages sent to contacts who have not messaged that number first will not be processed.
Endpoint
POST https://messenger.olly.bot/api/message
Payload 
interface ProviderOutgoingMessage {
  provider_number: string;  // Which sender number to use
  number: string;           // e.g. '+16207809306' or '[email protected]'
  group_id?: string;        // Reply to a specific group
  content?: string;
  url?: string;
}
Example 
curl -X POST https://messenger.olly.bot/api/message \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <api-key>" \
  -d '{
    "number": "+16208039306",
    "content": "hello world",
    "provider_number": "+12020304444"
  }'

Start Typing

Starts the typing indicator to the specified contact. The indicator stops once an outbound message is sent, or after 30 seconds.

Requires EXTRAS to be enabled on your account.
The typing indicator will not appear if: a) you have not sent the contact a message in the last 5 minutes, or b) you have not sent a message since the last typing indicator was sent.
Endpoint
POST https://messenger.olly.bot/api/typing/start
Payload 
interface ProviderTypingIndicator {
  number: string;           // e.g. '+16207809306' or '[email protected]'
  provider_number: string;  // Which sender number to use
}
Example 
curl -X POST https://messenger.olly.bot/api/typing/start \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <api-key>" \
  -d '{"number": "+16208039306"}'

Update Webhook

Set the publicly accessible URL that will receive notifications of incoming messages and outgoing message statuses.

Endpoint
POST https://messenger.olly.bot/api/webhook
Payload 
interface AccountWebhookUpdateRequest {
  url: string;
}
Example 
curl -X POST https://messenger.olly.bot/api/webhook \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <api-key>" \
  -d '{"url": "https://example.com/my-webhook"}'

Notification Webhooks

The payloads below will be forwarded to the webhook configured for your account. Match the type field to listen for specific events.

As a best practice, we will retry sending events if the request does not complete with a 200 status within the allowed timeframe. You may receive the same event multiple times — deduplicate by guid to avoid responding to the same message twice.

Status Update

Provides status updates on sent messages. Some non-terminal statuses may be skipped if the message has already reached a terminal state.

Payload 
interface ProviderMessageUpdate {
  type: "OutgoingMessageStatus";
  guid: string;
  number: string;
  group_id: string | null;
  provider_number: string;
  error: number;
  status: MessageStatus;
  service: "SMS" | "iMessage";
}

enum MessageStatus {
  QUEUED      = "QUEUED",      // Non-terminal
  SENT        = "SENT",        // Non-terminal
  DECLINED    = "DECLINED",
  RECEIVED    = "RECEIVED",
  DELIVERED   = "DELIVERED",
  ERROR       = "ERROR",
  UNKNOWN     = "UNKNOWN",
}

Message Received

Notifies when one of the account's numbers has received a message.

Payload 
interface ProviderIncomingMessage {
  type: "IncomingMessage";
  guid: string;
  number: string;
  content: string;
  group_id: string | null;
  provider_number: string;
  service: "SMS" | "iMessage";
}

Attachment Received

Notifies when an attachment is received. Attachments may include a corresponding message in content.

Payload 
interface ProviderIncomingAttachment {
  type: "IncomingAttachment";
  guid: string;
  number: string;
  content: string;
  group_id: string | null;
  provider_number: string;
  url: string;              // Full path to download attachment
  extension: string;
  filename: string;
  transfer_name: string;
  mime_type: string;
  total_bytes: number;
  is_sticker: number;
  service: "SMS" | "iMessage";
}