The Sms Webhook Notifier project allows to deliver a notification with the status of each message sent through the transactional API or the SMS Campaigns service, for customers who have an active configuration for this service.

Requirements for customer registration

For the registration of a new client in the Sms Webhook Notifier, it is necessary that the client has a POST type Endpoint without authentication restriction in its service API in order to receive the sending events. The request must be made to Masiv informing of the need and providing the following information:

  1. Id of the account to register the endpoint.
  2. Url of the client's endpoint that will receive the notifications.
  3. Size of the event batch (list of events) that you wish to receive. By default a Batch size of 3000 events per request is assigned (this means that Masiv in each notification request will send up to 3000 events in a Json type list).
  4. Type of events to be received (It is possible to configure the level one event that corresponds to the reception of the message by Masiv, and the level two event that corresponds to the definition and assignment of the message to the respective Mobile Operator).
  5. Type of traffic on which the event notification is expected (Transactional API and/or Campaigns).

Structure of the notified events

The following table specifies the possible attributes that an event notified by means of Sms Webhook Notifier may contain

<aside> 💡

Clarification: According to the Batch size configuration for each client, Sms Webhook Notifier will build a group according to the number of available and pending events to be notified and will send them through an HTTP POST request to the endpoint specified in the particular configuration of each client.

</aside>

Attribute Type Description
CampaignName String Name of the campaign selected in the platform for sending (Applies only to mailings made through Campaigns).
PackageId String Identifier of the mass mailing (Applies only to mailings made through Campaigns).
MessageId String Corresponds to the internal message ID.
Sent String, Datetime ISO 8601 Date the message was sent, UTC 0 format.
IdOperator String Corresponds to the operator's internal ID.
DestAddr String Destination cellular number of the SMS.
Status String (EventType) Corresponds to the message sending status, the possible statuses are specified in another table below.
ClientId Int Corresponds to the Id of the sending account.
ClientName String Corresponds to the name of the sending account.
Metadata Json Object Information sent by the client in the 'Metadata' parameter.
Reference String Corresponds to the Id of the message sent by the operator.
EventTime String, Datetime ISO 8601 Event generation date, UTC format.
MessageText String Corresponds to the text of the SMS sent.
Guid String Corresponds to the unique identifier of the message (internal Id assigned by Masiv).
Segments String Corresponds to the number of segments of the message.
Sender String Corresponds to the short code through which the message is sent.
Country String Corresponds to the code of the country to which the telephone number to which the message is being sent belongs.
Length Int Corresponds to the length of the message (number of characters).

An example of a notification would look as follows:

[
	{
		"CampaignName": "Prueba Sms",
		"PackageId": "3563063",
		"MessageId": "2035630631",
		"Sent": "0001-01-01T00:00:00",
		"IdOperator": "0",
		"DestAddr": "573132579839",
		"Status": "ReadyToSend",
		"ClientId": 6665,
		"ClientName": "Equiposms",
		"Metadata": null,
		"Reference": null,
		"Eventtime": "2023-04-12T22:14:36.318",
		"MessageText": "test campanas 05:13pm",
		"Guid": "c6b447cb-f544-465d-a219-d84291dbda67",
		"Segments": "1",
		"Sender": "87007",
		"Country": "CO",
		"Length": 21
	},
	{
		"CampaignName": "Prueba Sms 2",
		"PackageId": "3563067",
		"MessageId": "2035630665",
		"Sent": "0001-01-01T00:00:00",
		"IdOperator": "0",
		"DestAddr": "573132576789",
		"Status": "ReadyToSend",
		"ClientId": 6665,
		"ClientName": "Equiposms",
		"Metadata": null,
		"Reference": null,
		"Eventtime": "2023-04-12T22:15:36.318",
		"MessageText": "test campanas 03:36pm",
		"Guid": "c6b447cb-f544-465d-a219-d84291dfed56",
		"Segments": "2",
		"Sender": "87007",
		"Country": "CO",
		"Length": 23
	}
]

The possible values for the Status attribute are specified in the following table:

Status Description
ReadyToSend Means that the message has been correctly received by Masiv and is ready to be sent.
OperatorAssignment Means that the message has gone through the portability consultation process correctly and is already assigned to the corresponding mobile operator.
FormatError Means that the message has not passed successfully through the format validation process.
LengthError Means that the message type (Long, Short) is not in accordance with the length of the text to be sent
RepetitionError It means that there is a message with the same text and configuration for the same telephone number in the same campaign, and also the option of validation of repeats was enabled for this campaign.
Cancelled Means that the message belongs to a campaign that was cancelled.
UndefinedRoute Means that there is no route configured to link the sending client with the operator to which the SMS destination telephone number belongs.
TouchesRestricted Means that the message was restricted for having reached the limit of allowed touches (Law 2300 of Colombia).
ScheduleRestricted Means that the message was restricted because it was sent within the restricted hours (Law 2300 of Colombia).
UrlShortError Means that a failure occurred during the generation of the Short URL for the message.
Unsubscribed Means that the SMS destination phone number is within the list of unsubscribed numbers for the customer trying to send the message.
InsufficientCredits Means that the account trying to send the message does not have available credits to send the shipment, applies only to prepaid accounts.
PortabilityError Means that the operator to which the telephone number belongs is not identified by Masiv's Portability service or by the internal service of the numbering range mapping product.
Error Means that a general uncontrolled error occurred during message processing.