Unicom360.SMS (Unicom360 v0.1.0)

Send SMS (POST /api/v1/json/bulk/sms).

{:ok, result} =
  Unicom360.SMS.send(client, %{
    from: "Unicom360",
    to: ["260971234567", "260961234567"],
    message: "Your verification code is 482193. It expires in 5 minutes."
  })

for recipient <- result.results do
  IO.puts("#{recipient.mobile_number} #{recipient.status} #{recipient.message_id}")
end

The gateway accepts GSM-7 text only, at most 1,200 characters, and bills max(1, ceil(length / 160)) units per recipient. The SDK does not check this itself; see Unicom360.GSM to check before sending.

Summary

Types

params()

The SMS parameters, as a map or a keyword list

Functions

send(client, params, opts \\ [])

Sends an SMS to one or more numbers.

send!(client, params, opts \\ [])

Like send/3, but returns the result or raises Unicom360.Error.

Types

params()

@type params() ::
  %{
    :from => String.t(),
    :to => String.t() | [String.t()],
    :message => String.t(),
    optional(:user_reference_id) => String.t() | nil,
    optional(:callback_url) => String.t() | nil,
    optional(:source) => String.t() | nil
  }
  | keyword()

The SMS parameters, as a map or a keyword list:

:from (required) - a registered sender ID.
:to (required) - one number, or a list of numbers. International form ("2609...").
:message (required) - the text.
:user_reference_id - your reference. Makes the send safe to retry, and lets the gateway refuse a repeat (DUPLICATE_REFERENCE).
:callback_url - where the gateway posts delivery reports (unsigned; see Unicom360.Webhook.parse_sms_callback/1).
:source - a label for your reporting.

Functions

send(client, params, opts \\ [])

@spec send(Unicom360.Client.t(), params(), keyword()) ::
  {:ok, Unicom360.SMS.SendResult.t()} | {:error, Unicom360.Error.t()}

Sends an SMS to one or more numbers.

Returns {:ok, %Unicom360.SMS.SendResult{}}, whose results hold one entry per recipient. An invalid number among them is not an error: its entry's status is "Invalid mobile number" (see Unicom360.SMS.SendResult.invalid/1). Results are not in request order past the tenth recipient: find one with Unicom360.SMS.SendResult.by_number/2.

Fails with {:error, %Unicom360.Error{}}: for example code: "INVALID_SENDER_ID" or "INSUFFICIENT_BUNDLE" (an :api_error on HTTP 200).

Options: :timeout (ms per attempt) and :max_retries override the client's for this call. The send is retried after a failure that may have reached the gateway only when it has a user_reference_id.

send!(client, params, opts \\ [])

@spec send!(Unicom360.Client.t(), params(), keyword()) :: Unicom360.SMS.SendResult.t()

Like send/3, but returns the result or raises Unicom360.Error.