whatsapp_elixir

# WhatsappElixir

**WhatsappElixir** is an Elixir library for interacting with the WhatsApp API. It allows you to handle incoming messages and send responses efficiently using a clean and simple API.

## Installation

To use **WhatsappElixir** in your project, add it to your `mix.exs` dependencies:


```elixir
def deps do
  [
    {:whatsapp_elixir, "0.1.10"}
  ]
end
```

 ## Configuration

  Configure your WhatsApp credentials in `config/config.exs`:

      config :whatsapp_elixir,WhatsappElixir.HTTP,
        token: System.get_env("WHATSAPP_TOKEN"),
        phone_number_id: System.get_env("WHATSAPP_PHONE_NUMBER_ID"),
        verify_token: System.get_env("VERIFY_TOKEN")

  """

  Config can be left blank if you wish to pass the config at the app.

  ## Usage
  sending whatsapp message example this only works with users with existing sessions to send message first time use templated message on user reply session will be created. 

  ### messages & templated message

  ```elixir
  defmodule MyModule do
  alias WhatsappElixir.Messages

  def send_message(mobile_number) do
   Messages.send_message(mobile_number, "Hello World")
  end

  def send_templated(mobile_number) do
  Messages.send_template("hello_world", mobile_number, [] )
  end

 end
 ```

## Sends an image message to a WhatsApp user.

Args
  - image: Image id or link of the image
  - recipient_id: Phone number of the user with country code without +
  - recipient_type: Type of the recipient, either individual or group (default is "individual")
  - caption: Caption of the image (default is "")
  - link: Whether to send an image id or an image link, True means that the image is a link, False means that the image is an id (default is true)



```elixir
 iex> WhatsappElixir.send_image("https://i.imgur.com/Fh7XVYY.jpeg", "5511999999999")
 
```


## Send Template Message
```elixir
defmodule MyModule do
  alias WhatsappElixir.Messages

  def send_templated(mobile_number) do
    Messages.send_template("hello_world", mobile_number, [])
  end
end
```

## Handling inbound webhooks (phone numbers, BSUIDs and usernames)

Users who adopt a WhatsApp username may arrive **without a phone number**. In that case
`contacts[0].wa_id` and `messages[0].from` are missing, and the user is identified by a
business-scoped user ID (BSUID) such as `"KE.984051547420197"`. Use `get_sender/1`:

```elixir
alias WhatsappElixir.{Messages, Static}

def handle_webhook(params) do
  %{wa_id: wa_id, user_id: user_id, username: username, name: name} = Static.get_sender(params)

  # Every field can be nil. Store user_id as the stable key for username users.
  recipient = wa_id || user_id

  Messages.send_message(recipient, "Hi #{name || username}!")
end
```

Every send function takes either a phone number (sent as `"to"`) or a BSUID (sent as
`"recipient"`); see `WhatsappElixir.Recipient`. For status webhooks, use
`Static.get_status_recipient/1`, which returns `%{recipient_id: ..., recipient_user_id: ...}`.

## Send a WhatsApp Flow

Send a Flow as an interactive message inside the 24-hour customer service window:

```elixir
flow = %{
  flow_id: "1234567890",
  flow_token: "booking-42",          # returned to you in the user's reply
  flow_cta: "Book now",              # max 20 characters
  header: "Appointments",            # optional
  body: "Pick a time that suits you.",
  footer: "Takes 1 minute",          # optional
  screen: "BOOKING",                 # optional first screen
  data: %{"branch" => "nairobi"}     # optional, sent with the screen
  # mode: "draft"                    # to test an unpublished flow
}

{:ok, response} = WhatsappElixir.Flows.send_flow("254700000000", flow)
```

When the user submits the Flow, parse the reply webhook:

```elixir
case WhatsappElixir.Static.get_flow_response(params) do
  {:ok, flow_token, answers} -> handle_answers(flow_token, answers)
  :error -> :not_a_flow_reply
end
```