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:

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

  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)

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

Send Template Message

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:

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:

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:

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