Incoming Status Reports

🚧

Note

Status report webhooks are available in XML format and JSON format.

Once you have sent out messages via our Business Messaging API, you might want to receive status updates in return. These status updates can inform you about: how successful a campaign has been, who has received your message, or in case of failure, when a fallback has been applied. You can view the status updates on the CM-platform's messaging log or receive those statuses in your own system via a webhook.

  • API/Webhook - data in your own systems, development required, where also you need to adhere to GDPR.
  • Messaging log – data in CM's own platform, accessible for you 24/7, no development required, GDPR compliant.

There are no additional cost to use either one.
The Messaging platform has the option to communicate with a web server whenever a message updates its status. The status reports will be communicated using an HTTP POST request.

🚧

Note

Status reports sent towards an API/Webhook will be considered as not delivered when a non-successful response code is returned. Our services will temporarily hold the information and retry the delivery periodically for a maximum of 7 days. Status information will remain available through the Messaging Log.

Configure status reports

You can configure your status report webhook for SMS in the 'Channels'-app.
Please refer to the gateway section to configure your status reports.

You can choose to receive the status report in JSON format:


{
        "messages": {
            "msg": {
                "received": "[CREATED_S]",
                "to": "[GSM]",
                "reference": "[REFERENCE]",
                "status": {
                    "code": "[STATUS]",
                    "errorCode": "[STATUSDESCRIPTION]",
                    "errorDescription": "[STANDARDERRORTEXT]"
                },
                "operator": "[OPERATOR]"
            }
        }
 }

Or in XML format:


<MESSAGES>
	<MSG RECEIVED="[CREATED_S]">
		<TO>[GSM]</TO>
		<REFERENCE>[REFERENCE]</REFERENCE>
		<STATUS>
			<CODE>[STATUS]</CODE>
			<ERRORCODE>[STATUSDESCRIPTION]</ERRORCODE>
			<ERRORDESCRIPTION>[STANDARDERRORTEXT]</ERRORDESCRIPTION>
		</STATUS>
	</MSG>
</MESSAGES>

Parameter specification

NameFormatDescription
CreatedDatetimeThe moment when the status report was registered on CM.com's platform
SendDatetimeThe moment when the status report was sent to customer's/your endpoint
ToStringThe recipient of the message, such as the telephone number of the message recipient or another identifier
StatusIntegerThe code describing the current state of the message.
0 = accepted by the operator
1 = rejected by CM or operator
2 = delivered
3 = failed (message was not and will not be delivered)
4 = Read (Not for SMS, only other channels)
Standard ErrorStringThe description of the error if the message is in an error-state
Status DescriptionStringThe description of the current state of the message
ChannelStringThe used communication method via which the status report was received – ie. sms, whatsapp, viber.
OperatorStringThe Mobile Operator of the recipient - if relevant
ReferenceStringThe message reference which can be provided by the customer in the outbound message (see business messaging API)
CustomGrouping
CustomGrouping2
CustomGrouping3
StringThe custom groupings set for this Outbound Message (MT) (see business messaging API)

Note:

  • Date/time values are formatted as "yyyy-mm-ddThh:ii:ss" and provided in CEST.
  • Status implies the last known status of the message. You can expect multiple status updates, but you are not guaranteed to receive an update for each and every status change. For instance, receiving a status read implies it was delivered, even if you never received a report with status delivered. Similarly in some rare cases a status can become failed even after having received a previous status delivered. The reason for this is optimization by the various channel providers.

Standard Errors

Error codeShort descriptionFull description
5Message not delivered at third partyThe message has been confirmed as undelivered but no detailed information related to the failure is known.
7Message not delivered at operator because recipient has insufficient creditTemporary - Used to indicate to the client that the message has not yet been delivered due to insufficient subscriber credit but is being retried within the network.
8Message expired at third partyTemporary - Used when a message expired (could not be delivered within the life time of the message) within the operator SMSC but is not associated with a reason for failure.
20Message not delivered because of a malformed requestUsed when a message in its current form is undeliverable.
21Message expired at operatorTemporary - Only occurs where the operator accepts the message before performing the subscriber credit check. If there is insufficient credit then the operator will retry the message until the subscriber tops up or the message expires. If the message expires and the last failure reason is related to credit then this error code will be used.
22Message not delivered at operator because recipient has insufficient creditTemporary - Only occurs where the operator performs the subscriber credit check before accepting the message and rejects messages if there are insufficient funds available.
23Message not delivered because of an incorrect recipient number (invalid/blacklisted/barred)Used when the message is undeliverable due to an incorrect / invalid / blacklisted / permanently barred Phone Number for this operator. This Phone Number should not be used again for message submissions to this operator.
24Message not delivered because the recipient was unreachableTemporary - Used when a message is undeliverable because the subscriber is temporarily absent, e.g. his/her phone is switch off, he/she cannot be located on the network.
25Message not delivered at third partyTemporary - Used when the message has failed due to a temporary condition in the operator network. This could be related to the SS7 layer, SMSC or gateway.
26Message not delivered because of a temporary handset issue (sim card full/memory exceeded/SME busy)Temporary - Used when a message has failed due to a temporary phone related error, e.g. SIM card full, SME busy, memory exceeded etc. This does not mean the phone is unable to receive this type of message/content (refer to error code 27).
27Message not delivered because of a permanent handset issue (unable to receive SMS)Permanent - Used when a handset is permanently incompatible or unable to receive this type of message.
28Anti SPAM - Message not delivered because suspicion of SPAMUsed if a message fails or is rejected due to suspicion of SPAM on the operator network. This could indicate in some geographies that the operator has no record of the mandatory MO required for an MT.
29Message not delivered because content is not permittedPermanent - Used when this specific content is not permitted on the network / shortcode.
30Message not delivered because the set spend limit is reachedTemporary - Used when message fails or is rejected because the subscriber has reached the predetermined spend limit for the current billing period.
31Message not delivered because the recipient was suspended from premium servicesUsed when the Phone Number is for a valid subscriber on the operator but the message fails or is rejected because the subscriber is unable to be billed, e.g. the subscriber account is suspended (either voluntarily or involuntarily), the subscriber is not enabled for bill-tophone services, the subscriber is not eligible for bill-to-phone services, etc.
33Message not delivered because of parental lockUsed when the subscriber cannot receive adult content because of a parental lock.
34Message not delivered because age check failurePermanent - Used when the subscriber cannot receive adult content because they have previously failed the age verification process.
35Message not delivered because age check missingTemporary - Used when the subscriber cannot receive adult content because they have not previously completed age verification.
36Message not delivered because age check unavailableTemporary - Used when the subscriber cannot receive adult content because a temporary communication error prevents their status being verified on the age verification platform.
37Message not delivered because recipient is in national Do-Not-Call Register (for example, the Dutch SMS DienstenFilter and Chinese DnD list)The Phone Number is on the national blacklist
38Message not delivered because maximum concatenation tariff exceededUsed when the total tariff of a concatenated message exceeds the maximum tariff per message set by the operator
39Message not delivered because quota is emptyUsed when a customer is out of qouta.
40Message not delivered because the conversation window is closedMessage failed to send, conversation window closed. The channel specific conversation window is no longer open to send messages towards this customer.
41Message not delivered because too many messages were sent from this numberToo many messages send from this number, blocked notifications or marked as spam.
42Message not delivered because recipient is not capable to receive a message from this channelUsed when a recipient is not capable to receive a message from this channel. (For example, the user did not install WhatsApp).
43Message not delivered because a template related error occuredTemplate name does not exist for this language and namespace.
44Message not sent due to previous errors. Message not sent due to previous errors. Please contact support if this persists.
45User's number is part of an experiment. Failed to send message because this user's phone number is part of an experiment.
https://developers.facebook.com/docs/whatsapp/cloud-api/guides/experiments
47Message blocked by SafeguardUsed when the message was blocked because of security configuration, please check settings or contact the account manager
48Channel specific error, see detailsUsed when a supplier forwarded us information for which it is more convenient to look into the details. Usually only expected for rich channels such as WhatsApp. TheStatus Description will contain the details we have received from the supplier. Since the Business Messaging API is used for miscellaneous channels this error code will reflect channel specific error messages only.
49Message blocked by Safeguard Destination managementUsed when the message was blocked because of security configuration (destination management), please check settings or contact the account manager

Standard Errors WhatsApp

Read more about Standard Errors WhatsApp here.