WAservix (WAservix v1.0.0)

Copy Markdown View Source

Elixir client for the WAservix WhatsApp API Gateway.

WAservix links your own WhatsApp number by QR code (the same way WhatsApp Web does) and gives you a REST API to send text, images, documents, locations, polls and more.

client = WAservix.new(System.fetch_env!("WASERVIX_KEY"))
{:ok, %{"msgId" => id, "status" => "in_progress"}} =
  WAservix.send_text(client, "+15551234567", "Hello Aline, your order is ready")

Every function returns {:ok, data} (the decoded data field of the answer) or {:error, %WAservix.Error{}}. Keep the API key on your server.

API reference: https://tekservix.com/waservix/docs/

Summary

Types

result()

Result of every API call.

t()

A client. Create one with new/2 and reuse it.

Functions

connect_session(client, id, opts \\ [])

Connects a session by QR code, or by pairing code with phone: "+1555...".

create_session(client, params)

Creates a session.

delete_message(client, id)

Deletes a message.

edit_message(client, id, text)

Edits one of your own text messages (about 15 minutes after sending).

get_contact(client, phone)

One contact.

get_group_metadata(client, group_jid)

Group name, participants and settings.

get_message_info(client, id)

Message status: queued, sent, delivered, read, played or failed.

get_session(client, id)

One session.

get_session_qr_code(client, id)

QR code for linking the number.

get_status(client)

Connection status: connected, connecting, need_scan, disconnected, logged_out or expired.

get_user(client)

The linked WhatsApp account.

list_contacts(client)

Your contacts.

list_groups(client)

Groups the number belongs to.

list_sessions(client)

Sessions (need a personal access token, not a device key).

new(api_key, opts \\ [])

Creates a client with a device API key (Devices -> API key), or a personal access token for session management.

on_whatsapp(client, phone)

Is this number on WhatsApp? Returns {:ok, %{"exists" => true, "jid" => ...}}.

request(w_aservix, method, path, body \\ nil)

Calls any documented endpoint, e.g. request(client, :get, "/groups"). Returns the data field of the answer.

resend_message(client, id)

Resends a failed message.

save_contact(client, phone, name)

Saves or renames a contact.

send_document(client, to, document_url, opts \\ [])

Sends a document by URL. Options: :file_name, :caption.

send_image(client, to, image_url, opts \\ [])

Sends an image by URL. Option: :caption.

send_location(client, to, latitude, longitude, opts \\ [])

Sends a location pin. Option: :name.

send_message(client, to, fields)

Sends any message type to a number or group JID (...@g.us). fields uses the API names: text, imageUrl, videoUrl, audioUrl, documentUrl, fileName, stickerUrl, contact, location, poll, replyTo, mentions, viewOnce.

send_text(client, to, text)

Sends a text message.

verify_webhook(signature, secret)

Constant-time check of the X-Webhook-Signature header against your device's webhook secret.

Types

result()

@type result() :: {:ok, term()} | {:error, WAservix.Error.t()}

Result of every API call.

t()

@type t() :: %WAservix{req: Req.Request.t()}

A client. Create one with new/2 and reuse it.

Functions

connect_session(client, id, opts \\ [])

@spec connect_session(t(), term(), keyword()) :: result()

Connects a session by QR code, or by pairing code with phone: "+1555...".

create_session(client, params)

@spec create_session(t(), map()) :: result()

Creates a session.

delete_message(client, id)

@spec delete_message(t(), term()) :: result()

Deletes a message.

edit_message(client, id, text)

@spec edit_message(t(), term(), String.t()) :: result()

Edits one of your own text messages (about 15 minutes after sending).

get_contact(client, phone)

@spec get_contact(t(), String.t()) :: result()

One contact.

get_group_metadata(client, group_jid)

@spec get_group_metadata(t(), String.t()) :: result()

Group name, participants and settings.

get_message_info(client, id)

@spec get_message_info(t(), term()) :: result()

Message status: queued, sent, delivered, read, played or failed.

get_session(client, id)

@spec get_session(t(), term()) :: result()

One session.

get_session_qr_code(client, id)

@spec get_session_qr_code(t(), term()) :: result()

QR code for linking the number.

get_status(client)

@spec get_status(t()) :: result()

Connection status: connected, connecting, need_scan, disconnected, logged_out or expired.

get_user(client)

@spec get_user(t()) :: result()

The linked WhatsApp account.

list_contacts(client)

@spec list_contacts(t()) :: result()

Your contacts.

list_groups(client)

@spec list_groups(t()) :: result()

Groups the number belongs to.

list_sessions(client)

@spec list_sessions(t()) :: result()

Sessions (need a personal access token, not a device key).

new(api_key, opts \\ [])

@spec new(String.t(), keyword()) :: t()

Creates a client with a device API key (Devices -> API key), or a personal access token for session management.

Options:

  • :base_url - change only for testing
  • :receive_timeout - milliseconds to wait for an answer (default 30_000)
  • :req_options - extra options passed to Req.new/1 (proxy, plug for tests, ...)

on_whatsapp(client, phone)

@spec on_whatsapp(t(), String.t()) :: result()

Is this number on WhatsApp? Returns {:ok, %{"exists" => true, "jid" => ...}}.

request(w_aservix, method, path, body \\ nil)

@spec request(t(), atom(), String.t(), map() | nil) :: result()

Calls any documented endpoint, e.g. request(client, :get, "/groups"). Returns the data field of the answer.

resend_message(client, id)

@spec resend_message(t(), term()) :: result()

Resends a failed message.

save_contact(client, phone, name)

@spec save_contact(t(), String.t(), String.t()) :: result()

Saves or renames a contact.

send_document(client, to, document_url, opts \\ [])

@spec send_document(t(), String.t(), String.t(), keyword()) :: result()

Sends a document by URL. Options: :file_name, :caption.

send_image(client, to, image_url, opts \\ [])

@spec send_image(t(), String.t(), String.t(), keyword()) :: result()

Sends an image by URL. Option: :caption.

send_location(client, to, latitude, longitude, opts \\ [])

@spec send_location(t(), String.t(), number(), number(), keyword()) :: result()

Sends a location pin. Option: :name.

send_message(client, to, fields)

@spec send_message(t(), String.t(), map()) :: result()

Sends any message type to a number or group JID (...@g.us). fields uses the API names: text, imageUrl, videoUrl, audioUrl, documentUrl, fileName, stickerUrl, contact, location, poll, replyTo, mentions, viewOnce.

WAservix.send_message(client, "120363040000000000@g.us", %{text: "Team meeting at 3pm"})

send_text(client, to, text)

@spec send_text(t(), String.t(), String.t()) :: result()

Sends a text message.

verify_webhook(signature, secret)

@spec verify_webhook(String.t() | nil, String.t()) :: boolean()

Constant-time check of the X-Webhook-Signature header against your device's webhook secret.

WAservix.verify_webhook(get_req_header(conn, "x-webhook-signature") |> List.first(), secret)