DEFAULT_ENDPOINT
DEFAULT_ENDPOINT
The default XMS endpoint.
Client used to communicate with the XMS server.
This class will use the cURL functions to communicate with XMS. It is intended as a long lived object and can handle multiple requests.
For example, to send a simple parameterized text batch to three recipients we may use code such as
$client = new Clx\Xms\Client('{my-service-plan-id}', '{my-token}');
try {
$batchParams = new Clx\Xms\Api\MtBatchTextSmsCreate();
$batchParams->setSender('12345');
$batchParams->setRecipients(['987654321', '123456789', '567894321']);
$batchParams->setBody('Hello, ${name}!');
$batchParams->setParameters(
[
'name' => [
'987654321' => 'Mary',
'123456789' => 'Joe',
'default' => 'valued customer'
]
]
);
$batch = $client->createTextBatch($batchParams);
echo('The batch was given ID ' . $batch->getBatchId() . "\n");
} catch (Exception $ex) {
echo('Error creating batch: ' . $ex->getMessage() . "\n");
}
and to fetch a batch we may use the code (with $client
being the
same variable as above)
try {
$batch = $client->fetchBatch('{a batch identifier}');
echo('The batch was sent from ' . $batch->getSender() . "\n");
} catch (Exception $ex) {
echo('Error fetching batch: ' . $ex->getMessage() . "\n");
}
This client is aware of the PSR-3 logger interface and will log all requests at the debug level if given a logger through the \Clx\Xms\Client::setLogger() method.
__construct(string $servicePlanId, string $token, string $endpoint = \Clx\Xms\Client::DEFAULT_ENDPOINT)
Constructs a new XMS client.
The constructed client will communicate with the given endpoint using the given credentials. A default endpoint at CLX Communications is used if no endpoint is explicitly provided.
This client is not thread-safe.
string | $servicePlanId | the service plan identifier |
string | $token | the authentication token |
string | $endpoint | the XMS endpoint URL |
createTextBatch(\Clx\Xms\Api\MtBatchTextSmsCreate $batch) : \Clx\Xms\Api\MtBatchTextSmsResult
Creates a new text batch.
The text batch will be created as described in the given object.
\Clx\Xms\Api\MtBatchTextSmsCreate | $batch | the batch description |
the creation result
createBinaryBatch(\Clx\Xms\Api\MtBatchBinarySmsCreate $batch) : \Clx\Xms\Api\MtBatchBinarySmsResult
Creates a new binary batch.
The binary batch will be created as described in the given object.
\Clx\Xms\Api\MtBatchBinarySmsCreate | $batch | the batch description |
the creation result
createBatchDryRun(\Clx\Xms\Api\MtBatchSmsCreate $batch, integer|null $numRecipients = null) : \Clx\Xms\Api\MtBatchDryRunResult
Simulates sending the given batch.
The method takes an optional argument for instructing XMS to respond with per-recipient statistics, if non-null then this number of recipients will be returned in the result.
\Clx\Xms\Api\MtBatchSmsCreate | $batch | the batch to simulate |
integer|null | $numRecipients | number of recipients to show in per-recipient result |
result of dry-run
replaceTextBatch(string $batchId, \Clx\Xms\Api\MtBatchTextSmsCreate $batch) : \Clx\Xms\Api\MtBatchTextSmsResult
Replaces the batch with the given ID with the given text batch.
string | $batchId | identifier of the batch |
\Clx\Xms\Api\MtBatchTextSmsCreate | $batch | the replacement batch |
the resulting batch
replaceBinaryBatch(string $batchId, \Clx\Xms\Api\MtBatchBinarySmsCreate $batch) : \Clx\Xms\Api\MtBatchBinarySmsResult
Replaces the batch with the given ID with the given binary batch.
string | $batchId | identifier of the batch |
\Clx\Xms\Api\MtBatchBinarySmsCreate | $batch | the replacement batch |
the resulting batch
updateTextBatch(string $batchId, \Clx\Xms\Api\MtBatchTextSmsUpdate $batch) : \Clx\Xms\Api\MtBatchTextSmsResult
Updates the text batch with the given identifier.
string | $batchId | identifier of the batch |
\Clx\Xms\Api\MtBatchTextSmsUpdate | $batch | the update description |
the updated batch
updateBinaryBatch(string $batchId, \Clx\Xms\Api\MtBatchBinarySmsUpdate $batch) : \Clx\Xms\Api\MtBatchBinarySmsResult
Updates the binary batch with the given identifier.
string | $batchId | identifier of the batch |
\Clx\Xms\Api\MtBatchBinarySmsUpdate | $batch | the update description |
the updated batch
updateBatchTags(string $batchId, array<mixed,string> $tagsToAdd, array<mixed,string> $tagsToRemove) : array<mixed,string>
Updates the tags of the given batch.
string | $batchId | batch identifier |
array<mixed,string> | $tagsToAdd | tags to add to batch |
array<mixed,string> | $tagsToRemove | tags to remove from batch |
the updated batch tags
fetchBatch(string $batchId) : \Clx\Xms\Api\MtBatchSmsResult
Fetches the batch with the given batch identifier.
string | $batchId | batch identifier |
the corresponding batch
fetchBatches(\Clx\Xms\BatchFilter|null $filter = null) : \Clx\Xms\Api\Pages
Fetch the batches matching the given filter.
Note, calling this method does not actually cause any network traffic. Listing batches in XMS may return the result over multiple pages and this call therefore returns an object of the type \Clx\Xms\Api\Pages, which will fetch result pages as needed.
\Clx\Xms\BatchFilter|null | $filter | the batch filter |
the result pages
fetchDeliveryReport(string $batchId, string|null $type = null, array<mixed,string>|null $status = null, array<mixed,integer>|null $code = null) : \Clx\Xms\Api\BatchDeliveryReport
Fetches a delivery report for a batch.
The report type can be either "full" or "summary" and when "full" the report includes the individual recipients.
The report can be further limited by status and code. For example, to retrieve a summary report limited to messages having delivery status "Delivered" or "Failed" and codes "0", "11", or "400", one could call
$conn->fetchDeliveryReport(
'MyBatchId',
Clx\Xms\DeliveryReportType::SUMMARY,
['Delivered', 'Failed'],
[0, 11, 400]
);
If the non-identifier parameters are left as null
then the
XMS defaults are used. In particular, all statuses and codes
are included in the report.
string | $batchId | identifier of the batch |
string|null | $type | delivery report type |
array<mixed,string>|null | $status | statuses to fetch |
array<mixed,integer>|null | $code | codes to fetch |
the batch delivery report
fetchRecipientDeliveryReport(string $batchId, string $recipient) : \Clx\Xms\Api\BatchRecipientDeliveryReport
Fetches a delivery report for a specific batch recipient.
string | $batchId | the batch identifier |
string | $recipient | the batch recipient |
the delivery report
createGroup(\Clx\Xms\Api\GroupCreate $group) : \Clx\Xms\Api\GroupResult
Creates the given group.
\Clx\Xms\Api\GroupCreate | $group | group description |
the created group
replaceGroup(string $groupId, \Clx\Xms\Api\GroupCreate $group) : \Clx\Xms\Api\GroupResult
Replaces the group with the given group identifier.
string | $groupId | identifier of the group |
\Clx\Xms\Api\GroupCreate | $group | new group description |
the group after replacement
updateGroup(string $groupId, \Clx\Xms\Api\GroupUpdate $group) : \Clx\Xms\Api\GroupResult
Updates the group with the given identifier.
string | $groupId | identifier of the group |
\Clx\Xms\Api\GroupUpdate | $group | the update description |
the updated batch
updateGroupTags(string $groupId, array<mixed,string> $tagsToAdd, array<mixed,string> $tagsToRemove) : array<mixed,string>
Updates the tags of the given group.
string | $groupId | group identifier |
array<mixed,string> | $tagsToAdd | tags to add to group |
array<mixed,string> | $tagsToRemove | tags to remove from group |
the updated group tags
fetchGroup(string $groupId) : \Clx\Xms\Api\GroupResult
Fetches the group with the given group identifier.
string | $groupId | group identifier |
the corresponding group
fetchGroups(\Clx\Xms\GroupFilter|null $filter = null) : \Clx\Xms\Api\Pages
Fetch the groups matching the given filter.
Note, calling this method does not actually cause any network traffic. Listing groups in XMS may return the result over multiple pages and this call therefore returns an object of the type \Clx\Xms\Api\Pages, which will fetch result pages as needed.
\Clx\Xms\GroupFilter|null | $filter | the group filter |
the result pages
fetchInbound(string $inboundId) : \Clx\Xms\Api\MoSms
Fetches the inbound message with the given identifier.
The returned message is either textual or binary.
string | $inboundId | message identifier |
the fetched message
fetchInbounds(\Clx\Xms\InboundsFilter|null $filter = null) : \Clx\Xms\Api\Pages
Fetch inbound messages matching the given filter.
Note, calling this method does not actually cause any network traffic. Listing inbound messages in XMS may return the result over multiple pages and this call therefore returns an object of the type \Clx\Xms\Api\Pages, which will fetch result pages as needed.
\Clx\Xms\InboundsFilter|null | $filter | the inbound message filter |
the result pages