SMS Messaging with LaraCopilot Gateways

LaraCopilot routes outbound SMS through provider-specific gateways you configure in the admin panel. Each gateway maps to one upstream SMS provider and handles authentication, transport settings, and delivery receipt (DLR) callbacks automatically. Messages sent through a gateway are recorded and tied to both the gateway and the originating tenant, giving you a full audit trail from dispatch through delivery confirmation.

How SMS Gateways Work

Each SMS gateway represents a single upstream provider connection. When you send a message, LaraCopilot constructs the upstream endpoint from the gateway’s transport fields and posts the payload using HTTP Basic Auth. The fields that control this behaviour are:

Field	Type	Purpose
`provider_type`	string	Identifies the upstream provider (e.g. `smpp`, `http`)
`server_host`	string	Hostname or IP of the provider’s API server
`server_port`	integer	Port to connect on
`api_path`	string	Path appended to the host, defaults to `send`
`username`	string	HTTP Basic Auth username
`password`	string	HTTP Basic Auth password
`default_sender_id`	string	Fallback sender ID when none is specified per message
`callback_token`	string	Token used to authenticate inbound DLR callbacks
`use_ssl`	boolean	Whether to use HTTPS (`true`) or HTTP (`false`)
`is_active`	boolean	Gates whether the gateway accepts new send requests
`meta`	JSON object	Arbitrary provider-specific key/value pairs

Only gateways with is_active: true will process outbound messages. Deactivating a gateway does not affect messages already in a submitted state.

Configuring a Gateway and Sending Your First Message

Create the gateway

In the admin panel, navigate to SMS → Gateways and click New Gateway. Fill in name, provider_type, server_host, server_port, username, and password. Set use_ssl and is_active as appropriate for your provider, then save.

Verify the gateway is active

Confirm the gateway card shows is_active: true. If your provider requires a specific api_path (e.g. /api/v2/send), enter it in the API Path field — otherwise the platform defaults to send.

Send a message via the API

POST to /api/sms-gateways/{id}/send where {id} is the integer ID of the gateway. Supply the following JSON body:

{
  "to_number": "+14155550100",
  "from_sender": "LaraCopilot",
  "message": "Your verification code is 482910.",
  "tenant_id": 7,
  "callback_url": "https://your-app.example.com/webhooks/dlr"
}

{
  "message": "SMS request processed.",
  "data": {
    "id": 1024,
    "sms_gateway_id": 3,
    "tenant_id": 7,
    "to_number": "+14155550100",
    "from_sender": "LaraCopilot",
    "delivery_status": "submitted",
    "direction": "outbound",
    "external_message_id": "abc-123",
    "requested_at": "2026-04-22T10:00:00Z",
    "submitted_at": "2026-04-22T10:00:01Z"
  }
}

Parameter	Required	Description
`to_number`	Yes	Destination phone number, max 30 chars
`from_sender`	Yes	Sender ID or number shown to the recipient, max 30 chars
`message`	Yes	Message body, max 1,000 chars
`tenant_id`	No	Associates the message with a specific tenant
`callback_url`	No	URL to receive DLR callbacks; defaults to the platform’s built-in DLR endpoint for this gateway

Message Statuses

Every message moves through the following delivery_status lifecycle:

Status	Meaning
`queued`	Message created locally, not yet dispatched to the provider
`submitted`	Provider accepted the message and returned a success response
`delivered`	Provider confirmed delivery to the handset via DLR callback
`failed`	Dispatch attempt failed or the provider returned an error

The timestamps requested_at, submitted_at, and delivered_at are set automatically as the message advances through each state. The raw provider response is stored in remote_response, and any error detail is captured in error_message.

Delivery Receipts (DLR Callbacks)

When the provider delivers the message to the handset it calls the URL supplied in callback_url during dispatch. If you did not supply a custom URL, LaraCopilot uses its own DLR endpoint:

POST /api/sms-gateways/{id}/dlr

The endpoint looks for message_id, id, or messageId in the request body to match the original SmsMessage, then updates delivery_status and sets delivered_at to the current timestamp. The full callback payload is merged into the remote_response field for debugging.

If you supply a custom callback_url when sending, your server receives the DLR directly. You are responsible for forwarding it to the platform’s DLR endpoint, or for updating delivery_status through your own logic.

Set callback_token on the gateway and validate it in your custom DLR handler to prevent spoofed delivery receipts from third parties.

Get Started

Core Concepts

Features

Customer Portal

SMS Messaging with LaraCopilot Gateways

How SMS Gateways Work

Configuring a Gateway and Sending Your First Message

Message Statuses

Delivery Receipts (DLR Callbacks)

​How SMS Gateways Work

​Configuring a Gateway and Sending Your First Message

​Message Statuses

​Delivery Receipts (DLR Callbacks)

How SMS Gateways Work

Configuring a Gateway and Sending Your First Message

Message Statuses

Delivery Receipts (DLR Callbacks)