warb 1.0.0 → 1.0.1

data/docs/messages/interactive_call_to_action_url.md

@@ -28,7 +28,7 @@ Warb.interactive_call_to_action_url.dispatch(recipient_number) do |message|
   message.footer = "footer"
 
   # for header, there's a helper method to create a text header
-  message.set_text_header("Check this out!")
+  message.add_text_header("Check this out!")
 
   # and for action, you can use the build_action method to create a CTA action`
   message.build_action(button_text: "Click Here") do |action|
@@ -37,7 +37,7 @@ Warb.interactive_call_to_action_url.dispatch(recipient_number) do |message|
 end
 ```
 
-Aside from the text header, you can also set an image, video, or document as header using the respective methods, `set_image_header`, `set_video_header`, and `set_document_header`.
+Aside from the text header, you can also set an image, video, or document as header using the respective methods, `add_image_header`, `add_video_header`, and `add_document_header`.
 
 Here is an example of using an image as header:
 
@@ -47,7 +47,7 @@ Warb.interactive_call_to_action_url.dispatch(recipient_number) do |message|
   message.footer = "footer"
 
   # set an image as header
-  message.set_image_header(link: "https://example.com/image.jpg")
+  message.add_image_header(link: "https://example.com/image.jpg")
 
   # the build_action method also returns the built action
   action = message.build_action do |action|
@@ -68,7 +68,7 @@ Warb.interactive_call_to_action_url.dispatch(recipient_number) do |message|
 
   # set a document as header
   # for documents, you can also pass a filename. its extension will be used to determine the MIME type
-  message.set_document_header(link: "https://example.com/document.pdf", filename: "document.pdf")
+  message.add_document_header(link: "https://example.com/document.pdf", filename: "document.pdf")
 
   message.build_action(url: "https://example.com", button_text: "Click here")
 end
@@ -86,11 +86,11 @@ Here is a summary of the fields you can set in the `dispatch` method of the `int
 For header, as seen above, you can set it using the following instance methods:
 | Method                | Named Parameters   | Positional Parameters  | Respective Resource Class   |
 |-----------------------|--------------------|------------------------|-----------------------------|
-| `set_text_header`     | -                  | the content header     | `Warb::Resources::Text`     |
-| `set_image_header`    | `link`             | -                      | `Warb::Resources::Image`    |
-| `set_video_header`    | `link`             | -                      | `Warb::Resources::Video`    |
-| `set_document_header` | `link`, `filename` | -                      | `Warb::Resources::Document` |
+| `add_text_header`     | -                  | the content header     | `Warb::Resources::Text`     |
+| `add_image_header`    | `link`             | -                      | `Warb::Resources::Image`    |
+| `add_video_header`    | `link`             | -                      | `Warb::Resources::Video`    |
+| `add_document_header` | `link`, `filename` | -                      | `Warb::Resources::Document` |
 
 Under the hood, the set header methods will create the respective resource object and call its `build_header` method to prepare the header for sending.
 
-For the action, the `build_action` instance method will create a `Warb::Components::CTAAction` and return it
+For the action, the `build_action` instance method will create a `Warb::Components::CTAAction` and return it

data/docs/messages/interactive_list.md

@@ -77,7 +77,7 @@ Warb.interactive_list.dispatch(recipient_number) do |message|
   message.body = "Choose your preferred language"
   message.footer = "You can change it later"
 
-  message.set_text_header("Language Selection")
+  message.add_text_header("Language Selection")
 
   message.build_action(button_text: "Select") do |action|
     section = action.add_section(title: nil)
@@ -108,7 +108,7 @@ Warb.interactive_list.dispatch(recipient_number) do |message|
   message.body = "Choose your preferred language"
   message.footer = "You can change it later"
 
-  message.set_text_header("Language Selection")
+  message.add_text_header("Language Selection")
 
   message.build_action(button_text: "Select") do |action|
     action.add_section(title: "American Languages") do |american_section|

data/docs/messages/interactive_reply_button.md

@@ -23,7 +23,7 @@ Or you can use the block building strategy to simplify the process:
 
 ```ruby
 Warb.interactive_reply_button.dispatch(recipient_number) do |message|
-  message.set_image_header(media_id: "1341834336894773")
+  message.add_image_header(media_id: "1341834336894773")
 
   message.body = "Select a Language:"
   message.footer = nil
@@ -38,23 +38,23 @@ or you can build the action with the buttons texts directly, passing them to the
 
 ```ruby
 Warb.interactive_reply_button.dispatch(recipient_number, action: action) do |message|
-  message.set_text_header(content: "Options")
+  message.add_text_header(content: "Options")
   message.body = "Select a Language:"
   message.footer = nil
   message.build_action(buttons_texts: ["Português", "English", "Español"])
 end
 ```
 
-Aside from text and image headers, you can also set a video or document as header using the respective methods, `set_video_header` and `set_document_header`.
+Aside from text and image headers, you can also set a video or document as header using the respective methods, `add_video_header` and `add_document_header`.
 
-For text header, `set_text_header` receives a string, while for image, video, and document headers, you can pass a `media_id` or a `link` to the media file.
+For text header, `add_text_header` receives a string, while for image, video, and document headers, you can pass a `media_id` or a `link` to the media file.
 For header, as seen above, you can set it using the following instance methods:
 | Method                | Named Parameters               | Positional Parameters  | Respective Resource Class   |
 |-----------------------|--------------------------------|------------------------|-----------------------------|
-| `set_text_header`     | -                              | the content header     | `Warb::Resources::Text`     |
-| `set_image_header`    | `link`, `media_id`             | -                      | `Warb::Resources::Image`    |
-| `set_video_header`    | `link`, `media_id`             | -                      | `Warb::Resources::Video`    |
-| `set_document_header` | `link`, `media_id`, `filename` | -                      | `Warb::Resources::Document` |
+| `add_text_header`     | -                              | the content header     | `Warb::Resources::Text`     |
+| `add_image_header`    | `link`, `media_id`             | -                      | `Warb::Resources::Image`    |
+| `add_video_header`    | `link`, `media_id`             | -                      | `Warb::Resources::Video`    |
+| `add_document_header` | `link`, `media_id`, `filename` | -                      | `Warb::Resources::Document` |
 
 Either `link` or `media_id` can be used, but not both at the same time.
 
@@ -64,4 +64,4 @@ If you're using a `media_id`, it must be obtained from a previous upload using t
 
 The `filename` for the document header is optional, but if provided, it will be used to determine the MIME type of the document.
 
-For the `action` of the message, you can use the [`Warb::Components::ReplyButtonAction`](../components/reply_button_action.md) class to build the action with the buttons texts.
+For the `action` of the message, you can use the [`Warb::Components::ReplyButtonAction`](../components/reply_button_action.md) class to build the action with the buttons texts.

data/docs/messages/template.md

@@ -0,0 +1,373 @@
+# Template
+
+Template messages are used to send a message with a specific template.
+
+This is useful for sending messages that have a predefined structure, such as notifications or alerts.
+
+#### Quick Examples
+
+**Note**: For the examples below, take into account `Warb.setup` was called to configure the global client instance.
+
+List available templates:
+```ruby
+Warb.template.list
+```
+
+Sending template messages:
+```ruby
+Warb.template.dispatch(recipient_number, **params)
+```
+
+#### Listing Templates
+
+**Prerequisites**: In order to view templates, you need to have them available in your business account. For more details, refer to the [Meta documentation](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates/template-library). Template creation via API will be covered later in this documentation (coming soon).
+
+You can retrieve all available message templates:
+
+```ruby
+Warb.template.list
+```
+
+##### Optional Parameters
+
+You can optionally filter templates using various parameters:
+
+Limit the number of results:
+```ruby
+Warb.template.list(limit: 10)
+```
+
+Specify which template fields to return:
+```ruby
+Warb.template.list(fields: ["name", "status", "category"])
+```
+
+For a complete list of available fields, refer to the [Meta documentation](https://developers.facebook.com/docs/graph-api/reference/whats-app-business-hsm/#fields).
+
+##### Example Response
+
+```ruby
+{
+  "data" => [
+    {
+      "name" => "hello_world",
+      "status" => "APPROVED",
+      "category" => "UTILITY",
+      "language" => "en_US",
+      "components" => [ ... ],
+      "id" => "1282952826730729"
+    },
+    {
+      "name" => "other_template_001",
+      "status" => "APPROVED",
+      "category" => "MARKETING",
+      "language" => "pt_BR",
+      "components" => [ ... ],
+      "id" => "1948352829250167"
+    }
+  ],
+  "paging" => {
+    "cursors" => {
+      "before" => "...",
+      "after" => "..."
+    }
+  }
+}
+```
+
+#### Sending Template Messages
+
+To send  a template message, you need to provide the template name and the parameters for the template, if any.
+
+```ruby
+Warb.template.dispatch(recipient_number, **params)
+```
+
+Here, `**params` is a named hash parameters that will be passed to the template, as follow:
+| Attribute   | Type              | Required | Description                           |
+|-------------|-------------------|----------|---------------------------------------|
+| `name`      | `String`          | Yes      | The name of the template to use       |
+| `language`  | `String`          | Yes      | The language to use for the template  |
+| `resources` | `Array` or `Hash` | No       | The resources to use for the template |
+
+`name` must be the name of a template that has been created in the WhatsApp Business Platform.
+
+`language` must be a valid language code, such as `en_US` for English (United States) or `fr_FR` for French (France). Also, the specified template must support the specified language.
+
+> You can check `Warb::Language` for a list of supported languages.
+> If yours isn't there, you can refer to this [list with all supported languages](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/supported-languages) by WhatsApp.
+> Just use the value in the `code` column, and it will work.
+
+`resouces` can be an array or a hash of resources that will be used as parameters for the template. At this point, only `text`, `date_time` and `currency` are supported.
+
+If the template uses named parameters, then `resources` must be a hash, as follow:
+```ruby
+customer_name = Warb::Resources::Text.new(content: "Name")
+purchase_date = Warb::Resources::Text.new("January 1, 2023")
+
+Warb.template.dispatch(recipient_number, resources: {
+  customer_name: customer_name,
+  purchase_date: purchase_date
+}, name: "testing", language: "pt_BR")
+```
+
+If the template uses positional parameters, then `resources` must be an array, as follow:
+```ruby
+customer_name = Warb::Resources::Text.new(content: "Name")
+purchase_date = Warb::Resources::DateTime.new("January 1, 2023")
+
+Warb.template.dispatch(recipient_number, resources: [
+  customer_name,
+  purchase_date
+], name: "testing", language: "en_US")
+```
+
+In any case, under the hood, the resources instances' method `build_template_named_parameter` or `build_template_positional_parameter` will be called to build the template parameters accordingly.
+
+Instead of instatiating the resources manually, you can use helper methods as follow:
+```ruby
+Warb.template.dispatch(recipient_number) do |template|
+  template.name = "testing"
+  template.language = Warb::Language::PORTUGUESE_BR
+  template.add_text_parameter(content: "Name")
+  template.add_currency_parameter(code: "USD", amount: 11.42)
+end
+```
+
+Here, `add_text_parameter` and `add_currency_parameter` will build the resources for you with the given named parameters and add them to the template.
+
+Here's a table with all the helper methods you can use to add resources/paramters to the template message:
+| Method Name                     | Resource Type               | Description                                      |
+|---------------------------------|-----------------------------|--------------------------------------------------|
+| `add_text_parameter`            | `Warb::Resources::Text`     | Adds a text parameter to the template            |
+| `add_date_time_parameter`       | `Warb::Resources::DateTime` | Adds a date time parameter to the template       |
+| `add_currency_parameter`        | `Warb::Resources::Currency` | Adds a currency parameter to the template        |
+
+In the example above, notice we only used named parameters (no positional parameters) as arguments to the add parameter methods.
+
+So, the parameters will be built as positional parameters, and the `resources` will be an array.
+
+Also, the resources will be used to substitute the corresponding parameters in your template, in the same order they were added to the parameters/resources list.
+
+If you don't want to worry about the order of the parameters, you may use named parameters.
+
+For that, you have to pass the parameter name (as defined in your template) as the first argument to the helper method, as follow:
+```ruby
+Warb.template.dispatch(recipient_number, name: "testing", language: "pt_BR") do |template|
+  template.add_text_parameter("customer_name", content: "Name")
+  template.add_date_time_parameter("purchase_date", date_time: "January 1, 2023")
+end
+```
+
+This way, the order of the parameters names in the template and the order they were added with the `add_parameter` methods may be entirely different.
+
+One **IMPORTANT** thing to note is that, once defined, the type of the parameters won't be changed.
+
+So, in the following code:
+```ruby
+Warb.template.dispatch(recipient_number, name: "testing", language: "pt_BR") do |template|
+  template.add_date_time_parameter(date_time: "January 1, 2023")
+  template.add_text_parameter("customer_name", content: "Name")
+end
+```
+Your `customer_name` parameter won't behave the way you may expect.
+
+Since the first call to an `add_parameter` method was using the positional parameters syntax, then the internal resources attribute was set to an array, so that means any posterior calls to any `add_parameter` method will simply ignore the named parameter syntax and append the built resource to the list of positional parameters
+
+If the order of the calls was different:
+```ruby
+Warb.template.dispatch(recipient_number, name: "testing", language: "pt_BR") do |template|
+  template.add_text_parameter("customer_name", content: "Name")
+  template.add_date_time_parameter(date_time: "January 1, 2023")
+  template.add_currency_parameter(code: "USD", amount: 10)
+end
+```
+
+1. The first call to `add_parameter` method would set the internal resources/parameter to a hash, with a initial key named `customer_name`, pointing to a text resource
+
+2. Then the `DateTime` resource (built in the second call to `add_parameter` method) would be set as value to the key `""` (empty string) in the named parameter hash.
+
+3. Eventually, the `Currency` resource (in the third call do `add_parameter` method) would be set as value to the same key `""` (empty string) as the previous call, which would overwrite the previous resource.
+
+In this case, the call to the api would result in an error, either due to the mismatch of the count of parameters, or due to not having all named parameters defined.
+
+So, make sure to always use the same parameter syntax accordingly to your template.
+
+The add parameter methods also support block building as well:
+```ruby
+Warb.template.dispatch(recipient_number) do |template|
+  template.name = "testing"
+  template.language = Warb::Language::ENGLISH_US
+
+  template.add_text_parameter(content: "Name")
+
+  template.add_currency_parameter do |currency|
+    currency.code = "USD"
+    currency.amount = 11.42
+    currency.fallback = "$ 11.42"
+  end
+
+  template.add_date_time_parameter do |purchase_date|
+    purchase_date.date_time = "Jan 1st, 2024"
+  end
+end
+```
+
+If your template has any media header, you can set it as follow:
+| Header Type    | Template Instance Method    | Params                                         |
+|----------------|-----------------------------|------------------------------------------------|
+| `image`        | `add_image_header`          | `media_id` or `link`                           |
+| `video`        | `add_video_header`          | `media_id` or `link`                           |
+| `document`     | `add_document_header`       | `media_id` or `link`, `filename`               |
+| `location`     | `add_location_header`       | `latitude`, `longitude`, `name`, and `address` |
+| `text`         | `add_text_header`           | `content`, `parameter_name`                    |
+
+Every time a call is made to any `add_header` method, a new header will be set, overwriting the previous one.
+
+If you just want to change one attribute or another, `add_header` methods return the related resource, so it is possible to set the values if you keep a hold of such instance
+```ruby
+Warb.template.dispatch(recipient_number) do |template|
+  header = template.add_image_header(media_id: "wrong_media_id")
+
+  header.media_id = "correct_media_id"
+end
+```
+
+Also, either only one of `media_id` or `link` must be provided.
+
+The `media_id` must be the id of media uploaded previously to WhatsApp Business Platform, while the `link` must be a public acessible URL.
+
+Check the `upload` section for each media related message, like [`image`](./image.md) or [`document`](./document.md), for more info on how to upload and the supported formats.
+
+For the `document` header, `filename` is important because its extension will determine the preview capability on the recipient's device.
+
+For the `location` header, at least `latitude` and `longitude` must be provided.
+
+`add_header` methods will simply instatiate the corresponding resource class with the given parameters, and then, set it as the header attribute.
+
+For `text` header, note that, due to how the WhatsApp Business Platform works, you can't set the entire content for it (the same that happens with the body of the message).
+
+In this case, `add_text_header`, will simply use whatever was given to it as parameter to build the final header in the WhatsApp Business Platform.
+
+So, for example, if your tamplate header was created with `Hello, {{1}}!`, then the text passed to `add_text_header` will simply be substituted in that `{{1}}`.
+
+If your template was defined using named parameters instead (something like `Hello, {{customer_name}}!`), then you must pass the name of the paramter to `add_text_header` as follow:
+```ruby
+Warb.template.dispatch(recipient_number) do |template|
+  template.add_text_header(content: "John", parameter_name: "customer_name")
+end
+```
+
+When the template instance's `build_payload` method is called (which happens when the message is about to be dispatched), the header param will be created using the `header`'s `build_header` method.
+
+#### Adding Buttons
+
+If your template supports buttons, you can add them using the following methods:
+
+| Button Type        | Template Instance Method      | Params                                    |
+|--------------------|-------------------------------|-------------------------------------------|
+| `quick_reply`      | `add_quick_reply_button`      | `index`                                   |
+| `url`              | `add_dynamic_url_button`      | `index`, `text`                           |
+| `url`              | `add_auth_code_button`        | `index`, `text`                           |
+| `copy_code`        | `add_copy_code_button`        | `index`, `coupon_code`                    |
+| `voice_call`       | `add_voice_call_button`       | `index`                                   |
+| `flow`             | `add_flow_button`             | `index`, `flow_token`, `flow_action_data` |
+| `doesn't apply`    | `add_button`                  | `instance`, `&block`                      |
+
+You can either use the keyword parameters or set the attributes using a block:
+
+```ruby
+Warb.template.dispatch(recipient_number) do |template|
+  template.name = "order_confirmation"
+  template.language = Warb::Language::ENGLISH_US
+
+  # Add a quick reply button
+  template.add_quick_reply_button
+
+  # Add a dynamic URL button
+  template.add_dynamic_url_button do |button|
+    button.text = "dynamic-url-suffix"
+  end
+
+  # Add a copy auth code button
+  template.add_auth_code_button do |button|
+    button.text = "4UTHC0D3"
+  end
+
+  # Add a copy code button
+  template.add_copy_code_button(index: 2) do |button|
+    button.coupon_code = "SAVE20"
+  end
+
+  # Add a voice call button
+  template.add_voice_call_button
+
+  # Add a flow button
+  template.add_flow_button do |button|
+    button.flow_token = 'FLOWTOKEN'
+    button.flow_action_data = { name: 'John' }
+  end
+end
+```
+
+or if you'd rather to, you can add buttons using it's component and the `add_button` method:
+
+```ruby
+quick_reply_btn = Warb::Components::QuickReplyButton.new
+
+Warb.template.dispatch(recipient_number) do |template|
+  template.name = "order_confirmation"
+  template.language = Warb::Language::ENGLISH_US
+
+  # Add a quick reply button
+  template.add_button(quick_reply_btn)
+
+ # Add a quick reply button, passing a block.
+  template.add_button(quick_reply_btn) { |button| button.index = 1 }
+end
+```
+
+**Note**: The `index` parameter determines the order of the buttons in the template. Make sure the
+indices match the button positions defined in your template. The `index` is automaticaly set if you
+don't do it manually, but it is done based on the number of buttons added with the methods above,
+so if your template has a button that doesn't need configuration like the static url button you'll
+have provide the position of the other buttons.
+
+
+#### Creating Templates
+
+To create a template, you need to provide the template name, language, category and the body (components).
+
+```ruby
+Warb.template.create(
+  name: "my_template_001",
+  language: Warb::Language::ENGLISH_US,
+  category: Warb::Category::MARKETING,
+  body: Warb::Resources::Text.new(
+    text: "Hello {{1}}, welcome to our service!",
+    examples: ["John"]
+  )
+)
+```
+
+**Required Parameters:**
+| Parameter  | Type     | Description                                  |
+|------------|----------|----------------------------------------------|
+| `name`     | `String` | Unique template name (snake_case)            |
+| `language` | `String` | The language to use for the template         |
+| `category` | `String` | Template category (MARKETING, UTILITY, etc.) |
+
+**Template Categories:**
+- `Warb::Category::MARKETING` - Promotional content
+- `Warb::Category::UTILITY` - Transactional messages
+- `Warb::Category::AUTHENTICATION` - Security codes
+
+**Note**: Currently, the creation only supports body text, more resource types are coming soon.
+
+#### Deleting Templates
+
+To delete a template, you need to provide the template name.
+
+```ruby
+Warb.template.delete("my_template_001")
+```

data/docs/resources/README.md

@@ -0,0 +1,14 @@
+# Resources
+
+Most of the resources can be sent as message. Check the [messages](../messages/README.md) for detailed info.
+
+But there are some resources which act more like a component, not being used alone by themself.
+
+There are also, resources which can be used alone, and as components for other messages types, like the `Text` resource.
+
+Such resources, and where they are used, are listed bellow:
+| Resource                    | Documentation                | Used at                                                                              |
+|-----------------------------|------------------------------|--------------------------------------------------------------------------------------|
+| `Warb::Resources::Currency` | [Currency](./currency.md)    | [Template Messaging](../messages/template.md)                                        |
+| `Warb::Resources::DateTime` | [Date Time](./date_time.md)  | [Template Messaging](../messages/template.md)                                        |
+| `Warb::Resources::Text`     | [Text](./text.md)            | [Text Messaging](../messages/text.md), [Template Messaging](../messages/template.md) |

data/docs/resources/currency.md

@@ -0,0 +1,22 @@
+# Currency
+
+`Warb::Resources::Currency` is a resource, but different from most other resources, it can't be sent. Instead, it's used in a template message as one of its parameters.
+
+Please, refer to  our [templates messaging documentation](../messages/template.md) for more info.
+
+It represents an amount in a specific currency, which can be set with the following attributes:
+| Attribute  | Type               | Required | Description                                                 |
+|------------|--------------------|----------|-------------------------------------------------------------|
+| `amount`   | `Integer`, `Float` | Yes      | The amount to be represented in the given currency          |
+| `code`     | `String`           | Yes      | The code of the currency to be used                         |
+| `fallback` | `String`           | No       | A fallback value to be used in case the code can't be found |
+
+Since it is used in template messages, it implements both `build_template_named_parameter` and `build_template_positional_parameter`, which prepares the resource for using as parameter.
+
+If no `fallback` value is given, then a default one, based on the given `amount` and `currency` is used.
+
+In the WhatsApp Business Platform, the `code` will be used to represent the given `amount` according to the specific currency.
+
+But if the given code doesn't exist, or is not supported, then the given `fallback` value will be used instead.
+
+For the `code`, you must use one currency code like `USD` or `BRL`. `Warb::Resources::Currency` offers some of the most used currencies. You can also [check here](https://www.iso.org/iso-4217-currency-codes.html) for more detailed info and other available options.

data/docs/resources/date_time.md

@@ -0,0 +1,11 @@
+# Date Time
+
+`Warb::Resources::DateTime` is a resource, but different from most other resources, it can't be sent. Instead, it's used in a template message as one of its parameters.
+
+Please, refer to  our [templates messaging documentation](../messages/template.md) for more info.
+
+It simply represents a date time object, with the unique param/attribute being `date_time`.
+
+Although its name is `date_time`, its content can be any string, like `"January 1st"`, `"2020-01-01"` or `"Wednesday, Jan, 1st, 2020"`.
+
+Since it is used in template messages, it implements both `build_template_named_parameter` and `build_template_positional_parameter`, which prepares the resource for using as parameter.

data/docs/resources/text.md

@@ -0,0 +1,9 @@
+# Text
+
+`Warb::Resources::Text` is a resource, which represents a text.
+
+It can be used as a [simple message](../messages/text.md), as a text header for some interactive messages, like the [reply button message](../messages/interactive_reply_button.md) and as [parameters for templates](../messages/template.md) variables.
+
+In the [text messaging documentation](../messages/text.md) there is a table with the corresponding attributes.
+
+Aside from such attributes, `Text` resource also provides the `build_template_named_parameter` and `build_template_positional_parameter` methods, which are using under the hood for the template messaging feature.

data/docs/setup.md

@@ -43,4 +43,48 @@ Warb.setup do |config|
 end
 ```
 
-Also, note that calling `Warb.setup` multiple times **WILL NOT** override the previous configuration, so you can use it to change the global configuration at any time.
+Also, note that calling `Warb.setup` multiple times **WILL NOT** override the previous configuration, so you can use it to change the global configuration at any time.
+
+## Phone numbers (quality monitoring)
+
+You can fetch all phone numbers attached to your WhatsApp Business Account (WABA) and their quality/operational signals.
+
+Requirements: make sure you have configured a business_id in your global setup (this method uses the business context, not the sender/phone context).
+```ruby
+Warb.setup do |config|
+  config.access_token = "ACCESS_TOKEN"
+  config.business_id  = "BUSINESS_ID"      # <-- required here
+  config.sender_id    = "SENDER_ID"    # still used for message dispatch
+end
+```
+
+#### Global usage
+```ruby
+phones = Warb.list_phone_numbers
+```
+
+#### Sample response (unwrapped data array):
+```ruby
+=> [
+  {
+    "verified_name"            => "Test",
+    "code_verification_status" => "NOT_VERIFIED",
+    "display_phone_number"     => "00000000000",
+    "quality_rating"           => "GREEN",
+    "platform_type"            => "CLOUD_API",
+    "throughput"               => { "level" => "STANDARD" },
+    "webhook_configuration"    => { "application" => "https://example.com/" },
+    "id"                       => "(phone_number_id)"
+  }
+]
+```
+
+#### Notes
+
+This method returns the data array directly. If you need paging cursors, call the raw client:
+```ruby
+raw = Warb.client.get("phone_numbers", {}, endpoint_prefix: :business_id)
+raw.body # => { "data" => [...], "paging" => { "cursors" => {...} } }
+```
+
+Non-2xx responses raise Warb::RequestError (or subclasses), so you can rescue them in your app.

data/examples/audio.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
-require_relative "../lib/warb"
+require_relative '../lib/warb'
 
 # Configure your variables here
 
-access_token = ""
-business_id = ""
-sender_id = ""
-recipient_number = ""
+access_token = ''
+business_id = ''
+sender_id = ''
+recipient_number = ''
 
-audio_link = ""
+audio_link = ''
 
 # We recommend testing one section at a time, as it can be overwhelming to see all the messages at once.
 # So you can comment out the sections you don't want to test.
@@ -25,8 +25,8 @@ warb_from_setup = Warb.setup do |config|
 end
 
 # To send audio using its ID, you may need to retrieve it first, which can be retrieved this way
-file_path = "" # fill this in with the file path pointing to wherever the audio is located
-file_type = "" # fill this in with the mimetype of the audio to be uploaded
+file_path = '' # fill this in with the file path pointing to wherever the audio is located
+file_type = '' # fill this in with the mimetype of the audio to be uploaded
 # allow values for file_type: audio/aac, audio/amr, audio/mpeg, audio/mp4 or audio/ogg
 audio_id = warb_from_setup.audio.upload(file_path: file_path, file_type: file_type)
 # if you already have an audio id, you can simply replace the above line with such id
@@ -53,8 +53,8 @@ warb_from_new = Warb.new(
 )
 
 # Same as stated above, if you need an audio id, you can upload it this way
-file_path = "" # fill this in with the file path pointing to wherever the audio is located
-file_type = "" # fill this in with the mimetype of the audio to be uploaded
+file_path = '' # fill this in with the file path pointing to wherever the audio is located
+file_type = '' # fill this in with the mimetype of the audio to be uploaded
 # allow values for file_type: audio/aac, audio/amr, audio/mpeg, audio/mp4 or audio/ogg
 audio_id = warb_from_setup.audio.upload(file_path: file_path, file_type: file_type)
 # if you already have an audio id, you can simply replace the above line with such id