# `Unicom360.WhatsApp`
[🔗](https://github.com/TechRode-Solution-Limited/unicom360-elixir/blob/v0.1.0/lib/unicom360/whatsapp.ex#L1)

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])

# `template_params`

```elixir
@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.

# `send_session`

```elixir
@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!`

```elixir
@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`

```elixir
@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!`

```elixir
@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`

```elixir
@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!`

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

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

# `templates`

```elixir
@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!`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*