Document continueSending API field and FilterEvent removal reasons - #665
Document continueSending API field and FilterEvent removal reasons#665promptless-for-oss wants to merge 1 commit into
Conversation
Add the continueSending scheduling field to the Text Messages REST API reference (properties and PUT/PATCH tables) with a note on the publish-permission requirement and publishDown read-back. Document the optional reason parameter and REMOVAL_REASON_MISSING_NUMBER constant on FilterEvent in the SMS extension guide, scoping them to FilterEvent. Documents mautic/mautic#17310.
| @@ -69,6 +72,12 @@ Use these properties when creating a Text Message in a ``POST`` request. These p | |||
| - int | |||
| - How many times the SMS got sent | |||
There was a problem hiding this comment.
docs/rest_api/text_messages.rst:73-73 at b595045
continueSending is a non-nullable boolean column (continue_sending) defaulting to false; verified against Sms::loadMetadata field definition, matching the doc's "omit for default one-time send" and boolean type claims.
| @@ -69,6 +72,12 @@ Use these properties when creating a Text Message in a ``POST`` request. These p | |||
| - int | |||
| - How many times the SMS got sent | |||
There was a problem hiding this comment.
docs/rest_api/text_messages.rst:73-73 at b595045
Sms::setContinueSending(false) on a list-type SMS clears publishDown to null, matching the doc's "false sends once and ignores publishDown" claim.
|
|
||
| .. note:: | ||
|
|
||
| Writing or changing any schedule field - ``isPublished``, ``publishUp``, ``publishDown``, or ``continueSending`` - requires the ``sms:smses:publishown`` or ``sms:smses:publishother`` permission. Without it, Mautic ignores these fields on write. |
There was a problem hiding this comment.
docs/rest_api/text_messages.rst:77-77 at b595045
CommonApiController strips isPublished/publishUp/publishDown/continueSending from write parameters when the user lacks ':publishown' access and cannot access the entity for 'publish', matching "Mautic ignores these fields on write." SmsModel::getPermissionBase() returns 'sms:smses', and SmsProcessor.php hardcodes 'sms:smses:publishown'/'sms:smses:publishother' as the permission strings.
|
|
||
| Writing or changing any schedule field - ``isPublished``, ``publishUp``, ``publishDown``, or ``continueSending`` - requires the ``sms:smses:publishown`` or ``sms:smses:publishother`` permission. Without it, Mautic ignores these fields on write. | ||
|
|
||
| ``publishDown`` reads back as ``null`` for a one-time ``list`` SMS - one sent with ``continueSending`` set to false. |
There was a problem hiding this comment.
docs/rest_api/text_messages.rst:79-79 at b595045
Sms::getPublishDown() returns null when smsType is 'list' and continueSending is false, confirming publishDown reads back as null for a one-time list SMS.
| - Whether a scheduled Segment SMS - one with type ``list`` - keeps sending or sends once, defaulting to one-time when omitted. ``false`` sends once and ignores ``publishDown``, while ``true`` keeps sending with an optional later ``publishDown`` stop time. | ||
| * - ``language`` | ||
| - string | ||
| - Language locale of the SMS |
There was a problem hiding this comment.
docs/rest_api/text_messages.rst:322-322 at b595045
Same continueSending property row repeated in the PUT/PATCH parameters table; verified against the same Sms entity field definition as the POST properties table.
| * ``removeContacts(array $contacts)`` - Remove multiple Contacts | ||
| * ``getRemovedContacts()`` - Get the list of removed Contacts | ||
| * ``getContacts()`` - Returns the array of Contacts. | ||
| * ``removeContact(int $id, ?string $reason = null)`` - Remove a single Contact by ID. The ``reason`` is optional. |
There was a problem hiding this comment.
docs/plugin_extensions/sms.rst:204-204 at b595045
FilterEvent::removeContact(int $id, ?string $reason = null) signature matches the documented bullet exactly.
| * ``getRemovedContacts()`` - Get the list of removed Contacts | ||
| * ``getContacts()`` - Returns the array of Contacts. | ||
| * ``removeContact(int $id, ?string $reason = null)`` - Remove a single Contact by ID. The ``reason`` is optional. | ||
| * ``removeContacts(array $contacts, ?string $reason = null)`` - Remove multiple Contacts. The ``reason`` is optional. |
There was a problem hiding this comment.
docs/plugin_extensions/sms.rst:205-205 at b595045
FilterEvent::removeContacts(array $contacts, ?string $reason = null) signature matches the documented bullet exactly.
| * ``getContacts()`` - Returns the array of Contacts. | ||
| * ``removeContact(int $id, ?string $reason = null)`` - Remove a single Contact by ID. The ``reason`` is optional. | ||
| * ``removeContacts(array $contacts, ?string $reason = null)`` - Remove multiple Contacts. The ``reason`` is optional. | ||
| * ``getRemovedContacts(?string $reason = null)`` - Get the list of removed Contacts. Optionally pass a reason to return only the Contacts removed for that reason. |
There was a problem hiding this comment.
docs/plugin_extensions/sms.rst:206-206 at b595045
FilterEvent::getRemovedContacts(?string $reason = null) filters the removed list by reason when supplied, matching the documented bullet exactly.
| * ``removeContact(int $id, ?string $reason = null)`` - Remove a single Contact by ID. The ``reason`` is optional. | ||
| * ``removeContacts(array $contacts, ?string $reason = null)`` - Remove multiple Contacts. The ``reason`` is optional. | ||
| * ``getRemovedContacts(?string $reason = null)`` - Get the list of removed Contacts. Optionally pass a reason to return only the Contacts removed for that reason. | ||
| * ``FilterEvent::REMOVAL_REASON_MISSING_NUMBER`` - the reason value Mautic core records when it removes a Contact that has no phone number. |
There was a problem hiding this comment.
docs/plugin_extensions/sms.rst:207-207 at b595045
SendSmsSubscriber::genericFilter() calls $event->removeContacts(..., FilterEvent::REMOVAL_REASON_MISSING_NUMBER) for contacts with no phone number, confirming the constant is defined in FilterEvent (L12) and passed by SendSmsSubscriber during generic filtering.
| * ``getRemovedContacts(?string $reason = null)`` - Get the list of removed Contacts. Optionally pass a reason to return only the Contacts removed for that reason. | ||
| * ``FilterEvent::REMOVAL_REASON_MISSING_NUMBER`` - the reason value Mautic core records when it removes a Contact that has no phone number. | ||
|
|
||
| The ``reason`` parameters are optional, so existing subscribers stay backward compatible. |
There was a problem hiding this comment.
docs/plugin_extensions/sms.rst:209-209 at b595045
reason parameters default to null on FilterEvent::removeContact()/removeContacts(), so existing subscribers that omit the argument remain backward compatible.
| Use ``SmsEvents::FILTER_CONTACTS_ON_SEND`` for any remaining filtering logic, such as removing Contacts without phone numbers. Its listener receives a ``FilterEvent``. | ||
|
|
||
| All three event classes share a common API, shown here for :xref:`FilterEvent source`: | ||
| The methods below describe ``FilterEvent``, whose signatures come from :xref:`FilterEvent source`. The optional ``reason`` parameters and the ``REMOVAL_REASON_MISSING_NUMBER`` constant are specific to ``FilterEvent``. |
There was a problem hiding this comment.
docs/plugin_extensions/sms.rst:201-201 at b595045
FilterEvent alone defines optional ?string $reason params on removeContact/removeContacts/getRemovedContacts and the REMOVAL_REASON_MISSING_NUMBER constant; DncEvent.php and QueueEvent.php have no reason param or constant, confirming these are FilterEvent-specific as the framing sentence now states.
|
|
||
| The ``reason`` parameters are optional, so existing subscribers stay backward compatible. | ||
|
|
||
| ``getContacts()`` is common to all three events. ``DncEvent`` also exposes ``removeContact()``, ``removeContacts()``, and ``getRemovedContacts()``, but its ``removeContact()`` and ``removeContacts()`` take no ``reason`` parameter. ``QueueEvent`` instead exposes ``queueContact(int $id)``, ``queueContacts(array $contacts)``, and ``getQueuedContacts()``. |
There was a problem hiding this comment.
docs/plugin_extensions/sms.rst:211-211 at b595045
getContacts() is defined on FilterEvent, DncEvent, and QueueEvent. DncEvent::removeContact(int $id)/removeContacts(array $contacts)/getRemovedContacts() take no reason parameter (contrast with FilterEvent). QueueEvent has no remove* methods; it instead exposes queueContact(int $id), queueContacts(array $contacts), and getQueuedContacts() (see QueueEvent.php L20-L47 at the same commit), matching the paragraph exactly.
1 participant
Open in Promptless
Mautic 7.x adds a Schedule Send workflow for Segment Text Messages, which exposes a developer surface. This documents the new continueSending boolean on the Text Messages REST API (in the properties and PUT/PATCH parameter tables), with a note that writing any schedule field requires publish permission and that publishDown reads back as null for a one-time list SMS. It also documents the optional reason parameter added to FilterEvent's removeContact/removeContacts/getRemovedContacts and the FilterEvent::REMOVAL_REASON_MISSING_NUMBER constant in the SMS extension guide, scoping the reason API to FilterEvent (DncEvent and QueueEvent are unaffected).
Documents mautic/mautic#17310.
Trigger Events