action bulksms_post_messages { label: "Send Messages" description: "Send messages to one or more recipients.\n\nYou can post up to `30 000` messages in a batch. \nBut 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.\n\n#### Repliability\n\nWhen a sent message is _repliable_, the BulkSMS system can process an SMS response sent by your recipient.\n\nThe message sent by your customer is called a mobile originating (MO) message and would be available under `RECEIVED` messages. \nYou can obtain a list of MOs using the [retrieve messages API call](#tag/Message%2Fpaths%2F~1messages%2Fget).\nIn addition you can also get a list of the MOs that are associated with a specific sent message (see the [list related messages API call](#tag/Message%2Fpaths%2F~1messages~1%7Bid%7D~1relatedReceivedMessages%2Fget)).\n\nIf you use a specific _sender id_ in the `from` property of the send message, the message will not be repliable.\nIf you want a message to be repliable, you need to specify `REPLIABLE` in the `from.type` property.\n\nIf you do not set the `from` property, your account settings are considered to determine whether or not the message is repliable.\nIf the _default repliable_ setting on your account is _yes_ then the message will be repliable. \nIf this setting is _no_, the message will not be repliable.\n\n\n#### Body templates\n\nWhen sending a message you can use template fields to customise the message text.\n\n*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. \n\nFor 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 \n\n```\nGood morning {F0######}, your balance is {F1######}\n```\n\nIn 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.\n\nThe data fields are provided in the property named `fields` in the `to` element. Here is a complete example of how this might look\n\n```\n{\n \"body\": \"Good morning {F0######}, your balance is {F1######}\",\n \"to\": [\n {\"address\": \"27456789\",\"fields\": [\"Harry\", \"$1345.23\"] },\n {\"address\": \"27456785\",\"fields\": [\"Sally\", \"$2345.58\"] }\n ]\n}\n```\n\nIf 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. \n\n```\n{\n \"body\": \"Hi {fn######} {sn######}, have a great day!\",\n \"to\": [\n {\"address\": \"27456789\" },\n {\"address\": \"27456785\" }\n ]\n}\n```\n" provider: bulksms method: POST path: "/messages" encoding: json 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" } } } } }