Unicom360.WhatsApp (Unicom360 v0.1.0)

Copy Markdown View Source

WhatsApp Business messaging: approved templates, session messages inside the 24-hour customer service window, message status and the template list.

alias Unicom360.WhatsApp
alias Unicom360.WhatsApp.{Session, TemplateBody, TemplateHeader, TemplateRecipient}

{:ok, result} =
  WhatsApp.send_template(client, %{
    template: "order_ready",
    language: "en_US",
    recipients: [
      TemplateRecipient.new("260971234567",
        user_reference_id: "inv-42",
        header: TemplateHeader.image("https://example.com/receipts/ZM-4821.png"),
        body: TemplateBody.of(["Ada", "ZM-4821"])
      )
    ]
  })

{:ok, sent} = WhatsApp.send_session(client, Session.text("260971234567", "Ready!"))
{:ok, status} = WhatsApp.status(client, [sent.message_id])

Summary

Types

template_params()

The template send parameters, as a map or a keyword list

Functions

send_session(client, message, opts \\ [])

Sends a session message (free-form, inside the 24-hour customer service window).

send_session!(client, message, opts \\ [])

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

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

Sends an approved template to up to 1,000 recipients.

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

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

status(client, message_ids, opts \\ [])

The status of 1 to 100 messages, by the message_id a send returned.

status!(client, message_ids, opts \\ [])

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

templates(client, opts \\ [])

The account's approved templates, with their variables and buttons. Find one with Unicom360.WhatsApp.TemplateList.by_name/3. Options: :timeout (ms per attempt) and :max_retries.

templates!(client, opts \\ [])

Like templates/2, but returns the result or raises Unicom360.Error.

Types

template_params()

@type template_params() ::
  %{
    :template => String.t(),
    :recipients => [
      Unicom360.WhatsApp.TemplateRecipient.t() | map() | keyword()
    ],
    optional(:from) => String.t() | nil,
    optional(:language) => String.t() | nil,
    optional(:callback_url) => String.t() | nil
  }
  | keyword()

The template send parameters, as a map or a keyword list:

  • :template (required) - the approved template's name.
  • :recipients (required) - a list of Unicom360.WhatsApp.TemplateRecipient (or maps with the same keys).
  • :from - your WhatsApp number, when the account has several.
  • :language - the template's language ("en_US"), when it exists in several.
  • :callback_url - an https URL for this send's message.status webhooks.

Functions

send_session(client, message, opts \\ [])

@spec send_session(
  Unicom360.Client.t(),
  Unicom360.WhatsApp.SessionMessage.t() | map(),
  keyword()
) ::
  {:ok, Unicom360.WhatsApp.SessionSendResult.t()}
  | {:error, Unicom360.Error.t()}

Sends a session message (free-form, inside the 24-hour customer service window).

message is a Unicom360.WhatsApp.SessionMessage built with Unicom360.WhatsApp.Session, or a map in the API's shape, sent as given. Outside the window, fails with %Unicom360.Error{code: "SESSION_WINDOW_CLOSED"}: send a template instead.

Safe to retry after a failure that may have reached the gateway only with a user_reference_id. Options: :timeout (ms per attempt) and :max_retries.

send_session!(client, message, opts \\ [])

@spec send_session!(
  Unicom360.Client.t(),
  Unicom360.WhatsApp.SessionMessage.t() | map(),
  keyword()
) ::
  Unicom360.WhatsApp.SessionSendResult.t()

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

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

@spec send_template(Unicom360.Client.t(), template_params(), keyword()) ::
  {:ok, Unicom360.WhatsApp.TemplateSendResult.t()}
  | {:error, Unicom360.Error.t()}

Sends an approved template to up to 1,000 recipients.

Rejected recipients are not an error: see Unicom360.WhatsApp.TemplateSendResult.rejected/1. When every recipient is rejected, fails with %Unicom360.Error{code: "NO_VALID_RECIPIENTS"} (whose results say why).

Safe to retry after a failure that may have reached the gateway only when every recipient has a user_reference_id. Options: :timeout (ms per attempt) and :max_retries.

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

@spec send_template!(Unicom360.Client.t(), template_params(), keyword()) ::
  Unicom360.WhatsApp.TemplateSendResult.t()

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

status(client, message_ids, opts \\ [])

@spec status(Unicom360.Client.t(), [String.t()], keyword()) ::
  {:ok, Unicom360.WhatsApp.StatusResult.t()} | {:error, Unicom360.Error.t()}

The status of 1 to 100 messages, by the message_id a send returned.

The ids are sent as given (the gateway answers each distinct id once). An unknown id has status "NOT_FOUND". Find one with Unicom360.WhatsApp.StatusResult.by_id/2. Options: :timeout (ms per attempt) and :max_retries.

status!(client, message_ids, opts \\ [])

@spec status!(Unicom360.Client.t(), [String.t()], keyword()) ::
  Unicom360.WhatsApp.StatusResult.t()

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

templates(client, opts \\ [])

@spec templates(Unicom360.Client.t(), keyword()) ::
  {:ok, Unicom360.WhatsApp.TemplateList.t()} | {:error, Unicom360.Error.t()}

The account's approved templates, with their variables and buttons. Find one with Unicom360.WhatsApp.TemplateList.by_name/3. Options: :timeout (ms per attempt) and :max_retries.

templates!(client, opts \\ [])

@spec templates!(Unicom360.Client.t(), keyword()) ::
  Unicom360.WhatsApp.TemplateList.t()

Like templates/2, but returns the result or raises Unicom360.Error.