# `WAservix`
[🔗](https://github.com/TekservixHQ/waservix-elixir/blob/v1.0.0/lib/waservix.ex#L1)

Elixir client for the [WAservix WhatsApp API Gateway](https://tekservix.com/waservix/).

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/

# `result`

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

Result of every API call.

# `t`

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

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

# `connect_session`

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

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

# `create_session`

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

Creates a session.

# `delete_message`

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

Deletes a message.

# `edit_message`

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

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

# `get_contact`

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

One contact.

# `get_group_metadata`

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

Group name, participants and settings.

# `get_message_info`

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

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

# `get_session`

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

One session.

# `get_session_qr_code`

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

QR code for linking the number.

# `get_status`

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

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

# `get_user`

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

The linked WhatsApp account.

# `list_contacts`

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

Your contacts.

# `list_groups`

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

Groups the number belongs to.

# `list_sessions`

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

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

# `new`

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

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

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

# `request`

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

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

Resends a failed message.

# `save_contact`

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

Saves or renames a contact.

# `send_document`

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

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

# `send_image`

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

Sends an image by URL. Option: `:caption`.

# `send_location`

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

Sends a location pin. Option: `:name`.

# `send_message`

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

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

Sends a text message.

# `verify_webhook`

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

---

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