Skip to content

Latest commit

 

History

History
372 lines (263 loc) · 7.16 KB

text_messages.rst

File metadata and controls

372 lines (263 loc) · 7.16 KB
Raw

Text messages

Use this endpoint to obtain details on Mautic's Text Messages, or SMSs.

Text message properties

Use these properties when creating a Text Message in a POST request. These properties are also returned when listing or getting Text Messages.

Name Type Description
id int ID of the SMS
name string Title of the SMS
message string Message of the SMS
isPublished boolean Published state
publishUp datetime/null Date/time when the SMS gets published
publishDown datetime/null Date/time the SMS gets unpublished
dateAdded datetime Date/time SMS got created
createdBy int ID of the User that created the SMS
createdByUser string Name of the User that created the SMS
dateModified datetime/null Date/time SMS got last modified
modifiedBy int ID of the User that last modified the SMS
modifiedByUser string Name of the User that last modified the SMS
language string Language locale of the SMS
sentCount int How many times the SMS got sent

Using Mautic's API Library

You can interact with this API through the Mautic API Library as follows, or use the various http endpoints as described in this document.

<?php
use Mautic\MauticApi;
use Mautic\Auth\ApiAuth;

// ...
$initAuth = new ApiAuth();
$auth     = $initAuth->newAuth($settings);
$apiUrl   = "https://example.com";
$api      = new MauticApi();
$smsApi   = $api->newApi("smses", $auth, $apiUrl);

Get text message

<?php

//...
$sms = $smsApi->get($id);

Get an individual SMS by ID.

HTTP Request

GET /smses/ID

Response

Expected Response Code: 200

{  
    "sms":{  
        "isPublished":true,
        "dateAdded":"2016-09-14T12:14:45+00:00",
        "createdBy":1,
        "createdByUser":"Wu Popovski",
        "dateModified":null,
        "modifiedBy":null,
        "modifiedByUser":null,
        "id":1,
        "name":"Message A",
        "message":"Hello",
        "language":"en",
        "category":null,
        "publishUp":null,
        "publishDown":null,
        "sentCount":0
    }
}

List text messages

<?php
// ...

$smses = $smsApi->getList($searchFilter, $start, $limit, $orderBy, $orderByDir, $publishedOnly, $minimal);

HTTP Request

GET /smses

Query Parameters

Name Description
search String or search command to filter entities by.
start Starting row for the entities returned. Defaults to 0.
limit Limit number of entities to return. Defaults to the system configuration for pagination, which defaults to 30.
orderBy Column to sort by. Can use any column listed in the response.
orderByDir Sort direction: asc or desc.
publishedOnly Only return currently published entities.
minimal Return only array of entities without additional lists in it.

Response

Expected Response Code: 200

{  
    "total":1,
    "smses":[  
        {  
            "isPublished":true,
            "dateAdded":"2016-09-14T12:14:45+00:00",
            "createdBy":1,
            "createdByUser":"Kevin Bulgarelli",
            "dateModified":null,
            "modifiedBy":null,
            "modifiedByUser":null,
            "id":1,
            "name":"Message A",
            "message":"Hello",
            "language":"en",
            "category":null,
            "publishUp":null,
            "publishDown":null,
            "sentCount":0
        }
    ]
}

Properties

See the "Text message properties" on top of this document.

Create text message

<?php 

$data = array(
    'name'        => 'Text message A',
    'message' => 'This is my first sms created via API.',
    'isPublished' => 1
);

$sms = $smsApi->create($data);

Create a new SMS.

HTTP Request

POST /smses/new

POST Parameters

See the "Text message properties" on top of this document.

Response

Expected Response Code: 201

Properties

See the "Text message properties" on top of this document.

Edit text message

<?php

$id   = 1;
$data = array(
    'name'        => 'New sms name',
    'isPublished' => 0
);

// Create new a SMS of ID 1 is not found?
$createIfNotFound = true;

$sms = $smsApi->edit($id, $data, $createIfNotFound);

Edit a new SMS. Note that this supports PUT or PATCH depending on the desired behavior.

PUT creates an SMS if the given ID doesn't exist and clears all the SMS information, adds the information from the request. PATCH fails if the SMS with the given ID doesn't exist and updates the SMS field values with the values from the request.

HTTP Request

To edit an SMS and return a 404 if the SMS isn't found:

PATCH /smses/ID/edit

To edit an SMS and create a new one if the SMS isn't found:

PUT /smses/ID/edit

PUT/PATCH Parameters

Name Type Description
id int ID of the SMS
name string Title of the SMS
message string Message of the SMS
isPublished boolean Published state
publishUp datetime/null Date/time when the SMS should gets published
publishDown datetime/null Date/time the SMS should gets unpublished
language string Language locale of the SMS

Response

If PUT, the expected response code is 200 if the SMS got edited or 201 if created.

If PATCH, the expected response code is 200.

Properties

See the "Text message properties" on top of this document.

Delete text message

<?php

$sms = $smsApi->delete($id);

Delete an SMS.

HTTP Request

DELETE /smses/ID/delete

Response

Expected Response Code: 200

Properties

See the "Text message properties" on top of this document.

Send SMS to contact

<?php

$sms = $smsApi->sendToContact($smsId, $contactId);

Send a predefined SMS to existing Contact.

HTTP Request

GET /smses/ID/contact/CONTACT_ID/send

Response

Expected Response Code: 200

Properties

{
    "success": 1,
    "status": "Delivered"
}