SMS Gateways API — Configure Providers and Send Messages

LaraCopilot’s SMS gateway API lets you configure outbound messaging providers, send SMS messages, and inspect delivery history — all in a single resource. Each gateway holds its own connection credentials and sender identity, and every message sent through the API is recorded as an SmsMessage record that tracks status from queued through to delivered.

All SMS gateway endpoints require an active admin session. Requests without a valid session cookie return 401 Unauthorized.

List SMS gateways

Retrieve all configured SMS gateways. Pass search to filter by name, host, or provider type. Each result includes a messages_count field with the number of messages sent through that gateway.

GET /api/sms-gateways

Query parameters

string

Filter gateways by name, server_host, or provider_type. Matches partial strings.

Response

string

Human-readable status. Always "SMS gateways fetched successfully." on success.

object[]

Array of SMS gateway objects.

Show Gateway object properties

integer

Unique gateway identifier.

string

Display name for this gateway.

string

Gateway provider identifier (e.g. "jasmin", "smpp").

string

Hostname or IP address of the gateway server.

integer

TCP port the gateway listens on.

string

Path appended to the host and port to form the send URL.

string

Authentication username for the gateway.

string

Default originating address shown to recipients.

string

Token used to validate inbound DLR callbacks from the gateway.

boolean

Whether this gateway is enabled for sending.

boolean

Whether to connect to the gateway over HTTPS.

string

Free-text notes for internal reference.

object

Arbitrary key-value metadata stored alongside the gateway.

integer

Total number of messages sent through this gateway.

string

ISO 8601 timestamp when the gateway was created.

string

ISO 8601 timestamp of the last update.

Example request

curl https://your-instance.laracopilot.com/api/sms-gateways \
  -b cookies.txt

Filter by name

curl "https://your-instance.laracopilot.com/api/sms-gateways?search=jasmin" \
  -b cookies.txt

200 response

{
  "message": "SMS gateways fetched successfully.",
  "data": [
    {
      "id": 1,
      "name": "Jasmin Primary",
      "provider_type": "jasmin",
      "server_host": "sms.example.com",
      "server_port": 8080,
      "api_path": "send",
      "username": "admin",
      "default_sender_id": "LaraCopilot",
      "callback_token": "tok_abc123",
      "is_active": true,
      "use_ssl": false,
      "notes": null,
      "meta": null,
      "messages_count": 142,
      "created_at": "2024-01-15T10:00:00.000000Z",
      "updated_at": "2024-03-01T14:22:10.000000Z"
    }
  ]
}

Create a gateway

POST /api/sms-gateways

Request body

string

required

Display name for this gateway. Maximum 255 characters.

string

required

Gateway provider identifier. Maximum 100 characters (e.g. "jasmin", "smpp").

string

required

Hostname or IP address of the gateway server. Maximum 255 characters.

integer

required

TCP port the gateway listens on. Minimum value: 1.

string

Path segment appended after the host and port when building the send URL. Defaults to send when omitted. Maximum 255 characters.

string

required

Authentication username for Basic Auth. Maximum 255 characters.

string

required

Authentication password for Basic Auth. Maximum 255 characters.

string

Default originating address (alphanumeric sender ID or phone number). Maximum 30 characters.

string

Token included in DLR callback validation. Maximum 255 characters. See Webhooks for security guidance.

boolean

default:"false"

Set to true to enable this gateway for outbound sending.

boolean

default:"false"

Set to true to connect to the gateway over HTTPS.

string

Free-text internal notes. No length limit enforced by the API.

object

Arbitrary key-value object for custom metadata. Stored as JSON.

Response Returns the newly created gateway object at HTTP 201.

Example request

curl -X POST https://your-instance.laracopilot.com/api/sms-gateways \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Jasmin Primary",
    "provider_type": "jasmin",
    "server_host": "sms.example.com",
    "server_port": 8080,
    "api_path": "send",
    "username": "admin",
    "password": "s3cur3p4ss",
    "default_sender_id": "LaraCopilot",
    "callback_token": "tok_abc123",
    "is_active": true,
    "use_ssl": false
  }'

201 response

{
  "message": "SMS gateway created successfully.",
  "data": {
    "id": 1,
    "name": "Jasmin Primary",
    "provider_type": "jasmin",
    "server_host": "sms.example.com",
    "server_port": 8080,
    "api_path": "send",
    "username": "admin",
    "default_sender_id": "LaraCopilot",
    "callback_token": "tok_abc123",
    "is_active": true,
    "use_ssl": false,
    "notes": null,
    "meta": null,
    "created_at": "2024-03-20T09:15:00.000000Z",
    "updated_at": "2024-03-20T09:15:00.000000Z"
  }
}

Get a gateway

Fetch a single gateway by ID. The response includes messages_count.

GET /api/sms-gateways/{smsGateway}

Path parameters

integer

required

The ID of the SMS gateway to retrieve.

Example request

curl https://your-instance.laracopilot.com/api/sms-gateways/1 \
  -b cookies.txt

200 response

{
  "message": "SMS gateway loaded successfully.",
  "data": {
    "id": 1,
    "name": "Jasmin Primary",
    "provider_type": "jasmin",
    "server_host": "sms.example.com",
    "server_port": 8080,
    "api_path": "send",
    "username": "admin",
    "default_sender_id": "LaraCopilot",
    "callback_token": "tok_abc123",
    "is_active": true,
    "use_ssl": false,
    "notes": null,
    "meta": null,
    "messages_count": 142,
    "created_at": "2024-01-15T10:00:00.000000Z",
    "updated_at": "2024-03-01T14:22:10.000000Z"
  }
}

Update a gateway

Replace all fields on an existing gateway. Every required field from Create a gateway must be included. Use PATCH /api/sms-gateways/{smsGateway} for partial updates with the same field rules.

PUT /api/sms-gateways/{smsGateway}

Path parameters

integer

required

The ID of the SMS gateway to update.

Request body Accepts the same fields as Create a gateway. All required fields must be present.

Example request

curl -X PUT https://your-instance.laracopilot.com/api/sms-gateways/1 \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Jasmin Primary (updated)",
    "provider_type": "jasmin",
    "server_host": "sms2.example.com",
    "server_port": 8080,
    "username": "admin",
    "password": "n3wp4ss",
    "is_active": true,
    "use_ssl": true
  }'

200 response

{
  "message": "SMS gateway updated successfully.",
  "data": {
    "id": 1,
    "name": "Jasmin Primary (updated)",
    "provider_type": "jasmin",
    "server_host": "sms2.example.com",
    "server_port": 8080,
    "api_path": null,
    "username": "admin",
    "default_sender_id": "LaraCopilot",
    "callback_token": "tok_abc123",
    "is_active": true,
    "use_ssl": true,
    "notes": null,
    "meta": null,
    "created_at": "2024-01-15T10:00:00.000000Z",
    "updated_at": "2024-03-20T11:45:00.000000Z"
  }
}

Delete a gateway

Permanently delete a gateway. This action cannot be undone. Associated SmsMessage records are not automatically removed.

DELETE /api/sms-gateways/{smsGateway}

Path parameters

integer

required

The ID of the SMS gateway to delete.

Example request

curl -X DELETE https://your-instance.laracopilot.com/api/sms-gateways/1 \
  -b cookies.txt

200 response

{
  "message": "SMS gateway deleted successfully."
}

List messages for a gateway

Return all SmsMessage records associated with a gateway, ordered newest first. Use this to inspect delivery history for a specific gateway.

GET /api/sms-gateways/{smsGateway}/messages

Path parameters

integer

required

The ID of the SMS gateway whose messages you want to list.

Response

string

Always "SMS messages fetched successfully." on success.

object[]

Array of SMS message objects ordered by created_at descending.

Show Message object properties

integer

Unique message identifier.

integer

ID of the gateway that handled this message.

integer

Tenant that originated the message, or null for platform-level sends.

string

Destination phone number.

string

Originating address used for this message.

string

SMS body text.

string

Message ID returned by the gateway, or a generated UUID if the gateway did not return one.

string

Current delivery status: queued, submitted, delivered, or failed.

string

Always "outbound" for messages sent via this API.

string

URL the gateway will POST the DLR to.

object

Raw JSON response body returned by the gateway, merged with subsequent DLR payloads.

string

Error detail when delivery_status is failed, otherwise null.

string

ISO 8601 timestamp when the send request was received.

string

ISO 8601 timestamp when the gateway accepted the message.

string

ISO 8601 timestamp when the DLR confirmed delivery.

Example request

curl https://your-instance.laracopilot.com/api/sms-gateways/1/messages \
  -b cookies.txt

200 response

{
  "message": "SMS messages fetched successfully.",
  "data": [
    {
      "id": 57,
      "sms_gateway_id": 1,
      "tenant_id": 4,
      "to_number": "+447911123456",
      "from_sender": "LaraCopilot",
      "message": "Your verification code is 849201.",
      "external_message_id": "gw-msg-00992",
      "delivery_status": "delivered",
      "direction": "outbound",
      "callback_url": "https://your-instance.laracopilot.com/api/sms-gateways/1/dlr",
      "remote_response": {"message_id": "gw-msg-00992", "status": 0},
      "error_message": null,
      "requested_at": "2024-03-20T10:00:00.000000Z",
      "submitted_at": "2024-03-20T10:00:01.000000Z",
      "delivered_at": "2024-03-20T10:00:08.000000Z"
    }
  ]
}

Send an SMS

Dispatch an outbound SMS through the specified gateway. LaraCopilot creates an SmsMessage record with delivery_status: "queued", forwards the message to the gateway over HTTP(S) with Basic Auth, then updates the record to submitted or failed based on the gateway’s response. The final SmsMessage object — with its current delivery_status — is returned synchronously.

POST /api/sms-gateways/{smsGateway}/send

Path parameters

integer

required

The ID of the SMS gateway to send through.

Request body

string

required

Destination phone number in E.164 format (e.g. "+447911123456"). Maximum 30 characters.

string

required

Originating address shown to the recipient — alphanumeric sender ID or E.164 phone number. Maximum 30 characters.

string

required

SMS body text. Maximum 1000 characters.

integer

ID of the tenant on whose behalf the message is sent. Stored on the SmsMessage record for attribution. Optional.

string

URL where the gateway should POST delivery receipts. Must be a valid URL. Defaults to https://your-instance.laracopilot.com/api/sms-gateways/{id}/dlr when omitted.

Send flow

Record created

An SmsMessage record is created with delivery_status: "queued" and requested_at set to the current time.

Dispatch to gateway

LaraCopilot POSTs to {scheme}://{server_host}:{server_port}/{api_path} using Basic Auth credentials from the gateway. The payload includes to, from, content, dlr-url, dlr-level, and dlr-method.

Status updated

On a successful gateway response the record is updated to delivery_status: "submitted" and submitted_at is set. On any HTTP error or network exception the status is set to "failed" and error_message is populated.

Response returned

The refreshed SmsMessage record is returned. Poll GET /api/sms-gateways//messages or wait for the DLR webhook to confirm final delivery.

Response

string

Always "SMS request processed.".

object

The SmsMessage record after the gateway interaction.

Show Message object properties

integer

Unique message identifier.

integer

Gateway that handled this message.

integer

Tenant attribution, or null.

string

Destination phone number.

string

Originating address used.

string

SMS body text.

string

Message ID from the gateway response (message_id or id field), or a generated UUID.

string

"submitted" if the gateway accepted the request, "failed" if the gateway returned an error or the request timed out.

string

Always "outbound".

string

DLR callback URL sent to the gateway.

object

Parsed JSON body from the gateway response, or {"body": "<raw text>"} if the response was not valid JSON.

string

Error detail when delivery_status is "failed", otherwise null.

string

ISO 8601 timestamp when the send was initiated.

string

ISO 8601 timestamp when the gateway accepted the message, or null on failure.

string

ISO 8601 timestamp populated by the DLR webhook after delivery confirmation. null at this stage.

Example request

curl -X POST https://your-instance.laracopilot.com/api/sms-gateways/1/send \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "to_number": "+447911123456",
    "from_sender": "LaraCopilot",
    "message": "Your verification code is 849201.",
    "tenant_id": 4,
    "callback_url": "https://your-instance.laracopilot.com/api/sms-gateways/1/dlr"
  }'

200 response — submitted

{
  "message": "SMS request processed.",
  "data": {
    "id": 58,
    "sms_gateway_id": 1,
    "tenant_id": 4,
    "to_number": "+447911123456",
    "from_sender": "LaraCopilot",
    "message": "Your verification code is 849201.",
    "external_message_id": "gw-msg-00993",
    "delivery_status": "submitted",
    "direction": "outbound",
    "callback_url": "https://your-instance.laracopilot.com/api/sms-gateways/1/dlr",
    "remote_response": {"message_id": "gw-msg-00993", "status": 0},
    "error_message": null,
    "requested_at": "2024-03-20T12:00:00.000000Z",
    "submitted_at": "2024-03-20T12:00:01.000000Z",
    "delivered_at": null
  }
}

200 response — failed

{
  "message": "SMS request processed.",
  "data": {
    "id": 59,
    "sms_gateway_id": 1,
    "tenant_id": null,
    "to_number": "+447911999000",
    "from_sender": "LaraCopilot",
    "message": "Test message.",
    "external_message_id": "3f2a1c4b-...",
    "delivery_status": "failed",
    "direction": "outbound",
    "callback_url": "https://your-instance.laracopilot.com/api/sms-gateways/1/dlr",
    "remote_response": {"exception": "Connection refused"},
    "error_message": "Connection refused",
    "requested_at": "2024-03-20T12:05:00.000000Z",
    "submitted_at": null,
    "delivered_at": null
  }
}

Authentication

Resources

Messaging

SMS Gateways API — Configure Providers and Send Messages

List SMS gateways

Create a gateway

Get a gateway

Update a gateway

Delete a gateway

List messages for a gateway

Send an SMS

​List SMS gateways

​Create a gateway

​Get a gateway

​Update a gateway

​Delete a gateway

​List messages for a gateway

​Send an SMS

List SMS gateways

Create a gateway

Get a gateway

Update a gateway

Delete a gateway

List messages for a gateway

Send an SMS