Send Messages

v1.0.0

Send messages to one or more recipients.

You can post up to 30 000 messages in a batch. But note that the deduplication-id is set per submission, so it is recommended that you use a smaller number, like 4000 per submission in order to make resubmissions on network failures more practical.

Repliability

When a sent message is repliable, the BulkSMS system can process an SMS response sent by your recipient.

The message sent by your customer is called a mobile originating (MO) message and would be available under RECEIVED messages. You can obtain a list of MOs using the . In addition you can also get a list of the MOs that are associated with a specific sent message (see the ).

If you use a specific sender id in the from property of the send message, the message will not be repliable. If you want a message to be repliable, you need to specify REPLIABLE in the from.type property.

If you do not set the from property, your account settings are considered to determine whether or not the message is repliable. If the default repliable setting on your account is yes then the message will be repliable. If this setting is no, the message will not be repliable.

Body templates

When sending a message you can use template fields to customise the message text.

Field based templates allow you to create a message with place-holders for custom fields. Fields are identified by a zero based index; the first field is F0, the second is F1 and so on.

For example, let's say you want to send a daily SMS message to all your clients that tell them what their current balance is. The body of the message could look something like this

In this message, the first field, F0, is the name of the customer and he second field F1 is the balance for that customer. The # used to specify the maximum length of the field. Note that the maximum length allowed for the value includes the space taken by the braces, template name and hash symbol. For example, the value {F0#} specifies a maximum length of 5. If the data is longer than this length, the data will be truncated when the message body is constructed.

The data fields are provided in the property named fields in the to element. Here is a complete example of how this might look

{  "body": "Good morning {F0######}, your balance is {F1######}",  "to":  [      {"address": "27456789","fields": ["Harry", "$1345.23"] },      {"address": "27456785","fields": ["Sally", "$2345.58"] }  ]}

If you are sending to contacts (or to groups) in your phonebook, you can use the Phonebook based templates. These are similar to the templates described above, but they have specific names. The template for the contact's first name is identified by fn and the template for the contact's surname is identified by sn. Below in an example that will work if the numbers are registered in your phonebook.

Input

{
  "type": "object",
  "properties": {
    "auto-unicode": {
      "type": "boolean"
    },
    "deduplication-id": {
      "type": "integer",
      "format": "int32"
    },
    "schedule-date": {
      "type": "string",
      "format": "date-time"
    },
    "schedule-description": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

Output

{
  "type": "array",
  "items": {
    "type": "object",
    "required": [
      "id",
      "type",
      "to",
      "body",
      "status"
    ],
    "properties": {
      "body": {
        "description": "The content of the message",
        "type": "object"
      },
      "creditCost": {
        "type": "number",
        "format": "float",
        "description": "The cost of the message (in credits).   Note that this field does not have a value in the submission response."
      },
      "encoding": {
        "type": "string",
        "description": "The type of the content.  See the `encoding` field for more information.",
        "enum": [
          "TEXT",
          "UNICODE",
          "BINARY"
        ]
      },
      "from": {
        "type": "string",
        "description": "The address part of the sender id"
      },
      "id": {
        "type": "string",
        "description": "A unique identifier that is assigned when the message is created."
      },
      "messageClass": {
        "type": "integer",
        "format": "int32",
        "description": "See the `messageClass` field for more information."
      },
      "numberOfParts": {
        "type": "integer",
        "format": "int32",
        "description": "The number of parts.  If this is a concatenated message, the number of parts will be more than 1.  Note that this field does not have a value in the submission response."
      },
      "protocolId": {
        "type": "integer",
        "format": "int32",
        "description": "See the `protocolId` field for more information."
      },
      "relatedSentMessageId": {
        "type": "string",
        "description": "This field has a value only if the type is RECEIVED.\nWith SMS messages, it is not possible to link a reply directly with a specific sent message.  However, if you specified `REPLIABLE` in the `from` property, BulkSMS will link any reply to the most recent message sent to a given phone number.\n\nThe `relatedSentMessageId` property keeps the information about this link.\n\nYou can use this property to derive an implicit conversation from a set of messages.\n  - If a received reply message has a `relatedSentMessageId`, you can use it to retrieve the last message that was sent before the reply was received.\n  - If you have the `id` of the sent message and you want all the received messages that relate to it, you can use the List Related Messages Operation.\n"
      },
      "status": {
        "type": "object",
        "description": "The status of the message",
        "required": [
          "id",
          "type"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "A concatenated value A.B where A is the `status.type` and B is the `status.subtype`.  \nIt there is no value for `subtype` then B takes string value `\"null\"` (e.g. `\"SENT.null\"`).   \n"
          },
          "subtype": {
            "type": "string",
            "description": "Has a value only if the `type` is FAILED.\n\nEXPIRED  Delivery failed because message expired before delivery was possible.\n\nHANDSET_ERROR  Delivery failed because of a problem related to the phone (e.g. message storage area full).\n\nBLOCKED  Your account has been blocked from sending to this phone (e.g. recipient replied STOP to block communication).\n\nNOT_SENT  Message delivery was not attempted (e.g. because we were not able to find a route for the supplied phone number).\n",
            "enum": [
              "EXPIRED",
              "HANDSET_ERROR",
              "BLOCKED",
              "NOT_SENT"
            ]
          },
          "type": {
            "type": "string",
            "description": "\nACCEPTED  Message accepted for delivery. Only returned for initial message submissions.\n\nSCHEDULED  Message accepted for delivery at a later date. Only returned for initial message  submissions.\n\nSENT  Message has been relayed away from our systems.\n\nDELIVERED  Successfully delivered to phone.\n\nUNKNOWN  Message is in an unknown state.\n\nFAILED  Delivery failed.\n",
            "enum": [
              "ACCEPTED",
              "SCHEDULED",
              "SENT",
              "DELIVERED",
              "UNKNOWN",
              "FAILED"
            ]
          }
        }
      },
      "submission": {
        "type": "object",
        "description": "Identifies the submission.\n",
        "required": [
          "id",
          "date"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date-time",
            "description": "The date and time the submission was processed. If the `type` is RECEIVED, this field reflects the date and time the received message was processed."
          },
          "id": {
            "type": "string",
            "description": "A unique identity shared by all messages that were created from the same submission. This field should be ignored if the `type` is not SENT."
          }
        }
      },
      "to": {
        "type": "string",
        "description": "The phone number of the recipient"
      },
      "type": {
        "type": "string",
        "description": "The message direction",
        "enum": [
          "SENT",
          "RECEIVED"
        ]
      },
      "userSuppliedId": {
        "type": "string",
        "description": "This is the value you supplied in the `userSuppliedId` field.\nHas a value only if the `type` is SENT.\n"
      }
    }
  }
}