### Full Webhook Example

Source: https://api.covercut.com.br/docs/index.php

A complete example of a webhook payload, including headers and the body, for a new incoming message.

```APIDOC
Exemplo Completo (Headers + Body)
```json
{
  "headers": {
    "content-type": "application/json",
    "x-bsp-signature": "28a2a4200aaa6c457bfecca27d97f6a0b1dfef32f1bfa64b6aa8bfff2de4c429",
    "x-bsp-timestamp": "1778884885"
  },
  "body": {
    "event": "message",
    "from_number_id": "950147584848138",
    "contact": {
      "wa_id": "554799999999",
      "name": "Sandro"
    },
    "message": {
      "id": "wamid.HBgMNTU0N...",
      "type": "text",
      "text": "Ola"
    }
  }
}
```
```

--------------------------------

### Upload Media Example for Template

Source: https://api.covercut.com.br/docs/index.php

Upload an example media file (image, video, or document) required for templates with media headers. This endpoint returns the 'header_handle' needed for template creation.

```http
POST https://api.covercut.com.br/api/v1/media/upload_handle
```

--------------------------------

### Complete Webhook Payload Example (Headers + Body)

Source: https://api.covercut.com.br/docs/index.php

This example shows a complete webhook payload, including headers and the message body, for a new inbound message.

```json
{
  "headers": {
    "content-type": "application/json",
    "x-bsp-signature": "28a2a4200aaa6c457bfecca27d97f6a0b1dfef32f1bfa64b6aa8bfff2de4c429",
    "x-bsp-timestamp": "1778884885"
  },
  "body": {
    "event": "message",
    "from_number_id": "950147584848138",
    "contact": {
      "wa_id": "554799999999",
      "name": "Sandro"
    },
    "message": {
      "id": "wamid.HBgMNTU0N...",
      "type": "text",
      "text": "Ola"
    }
  }
}
```

--------------------------------

### Example Message Response

Source: https://api.covercut.com.br/docs/index.php

This is an example of a successful response when retrieving message details. It includes message ID, status, recipient, and creation timestamp.

```json
{
  "success": true,
  "messages": [
    {
      "wamid": "wamid.HBgLNTUxMTk5OTk5OTk5...",
      "status": "read",
      "recipient": "5511999990000",
      "created_at": "2025-01-10 14:32:00"
    }
  ]
}
```

--------------------------------

### Upload de Exemplo (Mídia)

Source: https://api.covercut.com.br/docs/index.php

Uploads an example media file required by Meta for templates with media headers. This endpoint returns the `header_handle` needed for template creation.

```APIDOC
## POST /api/v1/media/upload_handle

### Description
Uploads an example media file (image, video, or document) required by Meta for templates with media headers. This endpoint returns the `header_handle` needed for template creation.

### Method
POST

### Endpoint
/api/v1/media/upload_handle

### Request Body (Multipart)
- **file** (file) - Required - The image/video file (Max 5MB).
- **from** (string) - Required - The `phone_number_id` that will own the template.

### Response Example (200 OK)
```json
{
  "success": true,
  "header_handle": "h/4_C_A0B1C2D3E4F5G6H7I8J9K0L1M2N3O4P5Q6"
}
```
```

--------------------------------

### BSUID Examples

Source: https://api.covercut.com.br/docs/index.php

Examples of Business-Scoped User IDs (BSUID) formats, including numeric, phone-based, and username formats.

```text
BR.13491208655302741918      ← Formato numérico (CC.xxxxx)
BR.5519999999999             ← Com dígitos de telefone
joao.silva                   ← Username (após junho 2026)
```

--------------------------------

### Create Simplified Marketing Template

Source: https://api.covercut.com.br/docs/index.php

A simplified endpoint for quickly creating promotional templates that natively support CTA buttons. This example demonstrates a basic marketing template.

```json
{
  "name": "oferta_especial_maio",
  "language": "pt_BR",
  "components": [
    {
      "type": "BODY",
      "text": "Temos uma oferta especial para você!"
    }
  ]
}
```

--------------------------------

### GET Media Endpoint

Source: https://api.covercut.com.br/docs/index.php

Use this endpoint to retrieve media files. Add '&mode=stream' to receive the binary file directly.

```http
GET /api/v1/media/get?id={media_id}&from={phone_number_id}
```

--------------------------------

### Media Upload Response

Source: https://api.covercut.com.br/docs/index.php

Example successful response after uploading media for a template. It contains the 'header_handle' to be used in template creation.

```json
{
  "success": true,
  "header_handle": "h/4_C_A0B1C2D3E4F5G6H7I8J9K0L1M2N3O4P5Q6"
}
```

--------------------------------

### Message Events Payload Example

Source: https://api.covercut.com.br/docs/index.php

Example payload for incoming messages via webhooks, including event details, contact information, and message content.

```APIDOC
### Eventos de Mensagem

Exemplo de Payload — Nova Mensagem
```json
{
  "event": "message",
  "direction": "inbound",
  "contact": {
    "wa_id": "5547999999999",
    "user_id": "BR.13491208655302741918",
    "name": "João Silva"
  },
  "message": {
    "id": "wamid...",
    "type": "text",
    "text": "Oi!"
  }
}
```
```

--------------------------------

### Create Message Template (Named Variables)

Source: https://api.covercut.com.br/docs/index.php

Create a new message template using named variables (e.g., {{nome_cliente}}). This requires setting 'parameter_format' to 'NAMED' and structuring the 'example' block accordingly.

```json
{
  "name": "boas_vindas_nomeado",
  "category": "MARKETING",
  "language": "pt_BR",
  "parameter_format": "NAMED",
  "components": [
    {
      "type": "BODY",
      "text": "Olá {{nome_cliente}}, bem-vindo!",
      "example": {
        "body_text_named_params": [
          { "param_name": "nome_cliente", "example": "João" }
        ]
      }
    }
  ]
}
```

--------------------------------

### Create Message Template (Positional Variables)

Source: https://api.covercut.com.br/docs/index.php

Submit a new message template for Meta's review. This example shows how to use positional variables (e.g., {{1}}) in the template body.

```json
{
  "name": "boas_vindas",
  "category": "MARKETING",
  "language": "pt_BR",
  "components": [
    {
      "type": "BODY",
      "text": "Olá {{1}}, bem-vindo!",
      "example": {
        "body_text": [ ["João"] ]
      }
    }
  ]
}
```

--------------------------------

### SMB App State Sync Webhook Payload Example

Source: https://api.covercut.com.br/docs/index.php

This JSON payload represents the 'smb_app_state_sync' event, which is received after initial synchronization. It provides the complete phone book from the client's mobile WhatsApp Business application.

```json
{
  "event": "smb_app_state_sync",
  "from_number_id": "123456789012345",
  "smb_app_state_sync": {
    "contacts": [
      {
        "full_name": "Sandro Dev",
        "first_name": "Sandro",
        "phone_number": "5547999999999",
        "username": "sandro_dev",
        "user_id": "US.ENT.11815799212886844830"
      },
      {
        "full_name": "Maria Design",
        "first_name": "Maria",
        "phone_number": "5547888888888",
        "username": "maria_dsgn",
        "user_id": "US.ENT.99815799212886844112"
      }
    ]
  }
}
```

--------------------------------

### POST Catálogo Completo (Catalog Message)

Source: https://api.covercut.com.br/docs/index.php

Sends a button that opens the business's complete catalog on WhatsApp. An optional `thumbnail_product_retailer_id` can be provided to set the cover product.

```APIDOC
## POST /api/v1/messages/catalog (Catalog Message)

### Description
Sends a button that opens the complete business catalog on WhatsApp. The `thumbnail_product_retailer_id` parameter is optional and defines which product appears as the cover.

### Method
POST

### Endpoint
`/api/v1/messages/catalog`

### Parameters
#### Request Body
- **from** (string) - Required - Sender's phone number.
- **to** (string) - Required - Recipient's phone number.
- **type** (string) - Required - Message type, should be `"catalog_message"`.
- **body** (object) - Optional - Contains the text for the message body.
  - **text** (string) - Required - The text content of the message body.
- **footer** (object) - Optional - Contains the text for the message footer.
  - **text** (string) - Required - The text content of the message footer.
- **action** (object) - Required - Contains catalog message details.
  - **name** (string) - Required - Must be `"catalog_message"`.
  - **parameters** (object) - Required - Parameters for the catalog message.
    - **thumbnail_product_retailer_id** (string) - Optional - The SKU of the product to be displayed as the cover.

### Request Example
```json
{
  "from": "123456789012345",
  "to": "5547999999999",
  "type": "catalog_message",
  "body": {
    "text": "Confira todo o nosso catálogo com preços e disponibilidade em tempo real! 🛒"
  },
  "footer": {
    "text": "Entrega para todo o Brasil"
  },
  "action": {
    "name": "catalog_message",
    "parameters": {
      "thumbnail_product_retailer_id": "SKU_CAPA"
    }
  }
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the message was sent successfully.
- **message** (string) - Confirmation message.
- **message_id** (string) - The unique ID of the sent message.
- **from** (string) - Sender's phone number.
- **to** (string) - Recipient's phone number.

#### Response Example
```json
{
  "success": true,
  "message": "Mensagem de catálogo enviada com sucesso",
  "message_id": "wamid.HBgLNTU0Nzk5...",
  "from": "123456789012345",
  "to": "5547999999999"
}
```
```

```APIDOC
## POST /api/v1/messages/catalog (Catalog Message by BSUID)

### Description
Sends a button that opens the business's complete catalog on WhatsApp using the recipient's BSUID. An optional `thumbnail_product_retailer_id` can be provided to set the cover product.

### Method
POST

### Endpoint
`/api/v1/messages/catalog`

### Parameters
#### Request Body
- **from** (string) - Required - Sender's phone number.
- **recipient** (string) - Required - Recipient's BSUID.
- **type** (string) - Required - Message type, should be `"catalog_message"`.
- **body** (object) - Optional - Contains the text for the message body.
  - **text** (string) - Required - The text content of the message body.
- **footer** (object) - Optional - Contains the text for the message footer.
  - **text** (string) - Required - The text content of the message footer.
- **action** (object) - Required - Contains catalog message details.
  - **name** (string) - Required - Must be `"catalog_message"`.
  - **parameters** (object) - Required - Parameters for the catalog message.
    - **thumbnail_product_retailer_id** (string) - Optional - The SKU of the product to be displayed as the cover.

### Request Example
```json
{
  "from": "123456789012345",
  "recipient": "BR.13491208655302741918",
  "type": "catalog_message",
  "body": {
    "text": "Confira todo o nosso catálogo com preços e disponibilidade em tempo real! 🛒"
  },
  "footer": {
    "text": "Entrega para todo o Brasil"
  },
  "action": {
    "name": "catalog_message",
    "parameters": {
      "thumbnail_product_retailer_id": "SKU_CAPA"
    }
  }
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the message was sent successfully.
- **message** (string) - Confirmation message.
- **message_id** (string) - The unique ID of the sent message.
- **from** (string) - Sender's phone number.
- **to** (string) - Recipient's phone number.

#### Response Example
```json
{
  "success": true,
  "message": "Mensagem de catálogo enviada com sucesso",
  "message_id": "wamid.HBgLNTU0Nzk5...",
  "from": "123456789012345",
  "to": "5547999999999"
}
```
```

--------------------------------

### POST Multi-Produtos (Product List)

Source: https://api.covercut.com.br/docs/index.php

Displays a list of up to 30 products organized into up to 10 sections, ideal for storefronts and personalized recommendations.

```APIDOC
## POST /api/v1/messages/catalog (Product List)

### Description
Displays a list with up to 30 products organized into up to 10 sections. Ideal for storefronts and personalized recommendations.

### Method
POST

### Endpoint
`/api/v1/messages/catalog`

### Parameters
#### Request Body
- **from** (string) - Required - Sender's phone number.
- **to** (string) - Required - Recipient's phone number.
- **type** (string) - Required - Message type, should be `"product_list"`.
- **header** (object) - Optional - Contains the header information for the message.
  - **type** (string) - Required - Type of header, e.g., `"text"`.
  - **text** (string) - Required - The text content of the header.
- **body** (object) - Optional - Contains the text for the message body.
  - **text** (string) - Required - The text content of the message body.
- **footer** (object) - Optional - Contains the text for the message footer.
  - **text** (string) - Required - The text content of the message footer.
- **action** (object) - Required - Contains catalog and section information.
  - **catalog_id** (string) - Required - The ID of the catalog.
  - **sections** (array) - Required - An array of sections, each containing products.
    - **title** (string) - Required - The title of the section.
    - **product_items** (array) - Required - An array of product items within the section.
      - **product_retailer_id** (string) - Required - The SKU of the product.

### Request Example
```json
{
  "from": "123456789012345",
  "to": "5547999999999",
  "type": "product_list",
  "header": {
    "type": "text",
    "text": "Produtos em Destaque"
  },
  "body": {
    "text": "Selecionamos estes itens especialmente para você 🛍️"
  },
  "footer": {
    "text": "Frete grátis acima de R$200"
  },
  "action": {
    "catalog_id": "SEU_CATALOG_ID",
    "sections": [
      {
        "title": "Mais Vendidos",
        "product_items": [
          { "product_retailer_id": "SKU_1" },
          { "product_retailer_id": "SKU_2" },
          { "product_retailer_id": "SKU_3" }
        ]
      },
      {
        "title": "Novidades",
        "product_items": [
          { "product_retailer_id": "SKU_4" },
          { "product_retailer_id": "SKU_5" }
        ]
      }
    ]
  }
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the message was sent successfully.
- **message** (string) - Confirmation message.
- **message_id** (string) - The unique ID of the sent message.
- **from** (string) - Sender's phone number.
- **to** (string) - Recipient's phone number.

#### Response Example
```json
{
  "success": true,
  "message": "Mensagem de catálogo enviada com sucesso",
  "message_id": "wamid.HBgLNTU0Nzk5...",
  "from": "123456789012345",
  "to": "5547999999999"
}
```
```

```APIDOC
## POST /api/v1/messages/catalog (Product List by BSUID)

### Description
Displays a list of up to 30 products organized into up to 10 sections using the recipient's BSUID. Ideal for storefronts and personalized recommendations.

### Method
POST

### Endpoint
`/api/v1/messages/catalog`

### Parameters
#### Request Body
- **from** (string) - Required - Sender's phone number.
- **recipient** (string) - Required - Recipient's BSUID.
- **type** (string) - Required - Message type, should be `"product_list"`.
- **header** (object) - Optional - Contains the header information for the message.
  - **type** (string) - Required - Type of header, e.g., `"text"`.
  - **text** (string) - Required - The text content of the header.
- **body** (object) - Optional - Contains the text for the message body.
  - **text** (string) - Required - The text content of the message body.
- **footer** (object) - Optional - Contains the text for the message footer.
  - **text** (string) - Required - The text content of the message footer.
- **action** (object) - Required - Contains catalog and section information.
  - **catalog_id** (string) - Required - The ID of the catalog.
  - **sections** (array) - Required - An array of sections, each containing products.
    - **title** (string) - Required - The title of the section.
    - **product_items** (array) - Required - An array of product items within the section.
      - **product_retailer_id** (string) - Required - The SKU of the product.

### Request Example
```json
{
  "from": "123456789012345",
  "recipient": "BR.13491208655302741918",
  "type": "product_list",
  "header": {
    "type": "text",
    "text": "Produtos em Destaque"
  },
  "body": {
    "text": "Selecionamos estes itens especialmente para você 🛍️"
  },
  "footer": {
    "text": "Frete grátis acima de R$200"
  },
  "action": {
    "catalog_id": "SEU_CATALOG_ID",
    "sections": [
      {
        "title": "Mais Vendidos",
        "product_items": [
          { "product_retailer_id": "SKU_1" },
          { "product_retailer_id": "SKU_2" },
          { "product_retailer_id": "SKU_3" }
        ]
      },
      {
        "title": "Novidades",
        "product_items": [
          { "product_retailer_id": "SKU_4" },
          { "product_retailer_id": "SKU_5" }
        ]
      }
    ]
  }
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the message was sent successfully.
- **message** (string) - Confirmation message.
- **message_id** (string) - The unique ID of the sent message.
- **from** (string) - Sender's phone number.
- **to** (string) - Recipient's phone number.

#### Response Example
```json
{
  "success": true,
  "message": "Mensagem de catálogo enviada com sucesso",
  "message_id": "wamid.HBgLNTU0Nzk5...",
  "from": "123456789012345",
  "to": "5547999999999"
}
```
```

--------------------------------

### Send Carousel Media Message

Source: https://api.covercut.com.br/docs/index.php

Examples for sending carousel media messages with URL buttons (CTA URL) and quick reply buttons. The parameter table includes all card fields (header, body, action), and a success response example is provided.

```json
POST /api/v1/messages/carousel
```

--------------------------------

### Send Product List Message

Source: https://api.covercut.com.br/docs/index.php

Use this endpoint to display a list of up to 30 products organized into up to 10 sections, ideal for showcases and personalized recommendations. The header, body, and footer are optional.

```json
{
  "from": "123456789012345",
  "to": "5547999999999",
  "type": "product_list",
  "header": {
    "type": "text",
    "text": "Produtos em Destaque"
  },
  "body": {
    "text": "Selecionamos estes itens especialmente para você 🛍️"
  },
  "footer": {
    "text": "Frete grátis acima de R$200"
  },
  "action": {
    "catalog_id": "SEU_CATALOG_ID",
    "sections": [
      {
        "title": "Mais Vendidos",
        "product_items": [
          { "product_retailer_id": "SKU_1" },
          { "product_retailer_id": "SKU_2" },
          { "product_retailer_id": "SKU_3" }
        ]
      },
      {
        "title": "Novidades",
        "product_items": [
          { "product_retailer_id": "SKU_4" },
          { "product_retailer_id": "SKU_5" }
        ]
      }
    ]
  }
}
```

```json
{
  "from": "123456789012345",
  "recipient": "BR.13491208655302741918",
  "type": "product_list",
  "header": {
    "type": "text",
    "text": "Produtos em Destaque"
  },
  "body": {
    "text": "Selecionamos estes itens especialmente para você 🛍️"
  },
  "footer": {
    "text": "Frete grátis acima de R$200"
  },
  "action": {
    "catalog_id": "SEU_CATALOG_ID",
    "sections": [
      {
        "title": "Mais Vendidos",
        "product_items": [
          { "product_retailer_id": "SKU_1" },
          { "product_retailer_id": "SKU_2" },
          { "product_retailer_id": "SKU_3" }
        ]
      },
      {
        "title": "Novidades",
        "product_items": [
          { "product_retailer_id": "SKU_4" },
          { "product_retailer_id": "SKU_5" }
        ]
      }
    ]
  }
}
```

--------------------------------

### GET / POST Link de Convite

Source: https://api.covercut.com.br/docs/index.php

Obtains or resets the group's invitation link.

```APIDOC
## GET / POST Link de Convite

### Description
Obtains or resets the group's invitation link.

### Method
GET or POST

### Endpoint
`/api/v1/groups/{group_jid}/invite` (Assumed endpoint based on common API patterns for invite links)

### Parameters
#### Path Parameters
- **group_jid** (string) - Required - The unique identifier of the group.

#### Query Parameters (for GET)
None explicitly mentioned, but typically used to retrieve the link.

#### Request Body (for POST - to reset)
None explicitly mentioned, but a POST request to this endpoint would typically imply a reset action.

### Response
#### Success Response (200)
- **invite_link** (string) - The invitation link for the group.
```

--------------------------------

### API Synchronization Success Response

Source: https://api.covercut.com.br/docs/index.php

Example of a successful response when initiating a synchronization request via the API.

```JSON
{
  "success": true,
  "message": "Sincronização iniciada com sucesso. Os dados serão transmitidos assincronamente em pacotes via Webhook.",
  "results": {
    "contacts": "Iniciado (contacts_sync_req_01)",
    "history": "Iniciado (history_sync_req_02)"
  }
}
```

--------------------------------

### Create Template with Payment Request Buttons (Brazil)

Source: https://api.covercut.com.br/docs/index.php

Create a template for payment requests in Brazil, supporting PIX, Boleto, and payment links. This structure allows for up to three payment buttons per template.

```json
{
  "from": "123456789012345",
  "name": "cobranca_pagamento",
  "category": "UTILITY",
  "language": "pt_BR",
  "components": [
    {
      "type": "BODY",
      "text": "Olá, {{1}}! Sua fatura de R$ {{2}} está disponível. Escolha a forma de pagamento:"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "PAYMENT_REQUEST",
          "text": "Copy Pix code",
          "payment_setting": {
            "type": "pix_dynamic_code",
            "pix_dynamic_code": { "code": "00020101021226700014br.gov.bcb.pix..." }
          }
        },
        {
          "type": "PAYMENT_REQUEST",
          "text": "Copy Boleto code",
          "payment_setting": {
            "type": "boleto",
            "boleto": { "digitable_line": "03399026944140000002628346101018898510000008848" }
          }
        },
        {
          "type": "PAYMENT_REQUEST",
          "text": "Open payment link",
          "payment_setting": {
            "type": "payment_link",
            "payment_link": { "uri": "https://exemplo.com/pagar/123" }
          }
        }
      ]
    }
  ]
}
```

--------------------------------

### Get Group Invite Link

Source: https://api.covercut.com.br/docs/index.php

Retrieves an invite link for a specified group. Requires the group ID and a phone number ID.

```http
GET /api/v1/groups/invite_link?group_id=GROUP_ID&from=PHONE_NUMBER_ID
```

--------------------------------

### Criar Template de Marketing (Simplificado)

Source: https://api.covercut.com.br/docs/index.php

A simplified version for quickly creating promotional templates with native support for CTA buttons.

```APIDOC
## POST /api/v1/templates/marketing/create

### Description
A simplified version for quickly creating promotional templates with native support for CTA buttons.

### Method
POST

### Endpoint
/api/v1/templates/marketing/create

### Request Body
```json
{
  "name": "oferta_especial_maio",
  "language": "pt_BR",
  "components": [
    {
      "type": "BODY",
      "text": "Temos uma oferta especial para você!"
    }
  ]
}
```
```

--------------------------------

### GET Obter Mídia

Source: https://api.covercut.com.br/docs/index.php

Retrieves media using its ID and an optional phone number identifier. Supports streaming binary data.

```APIDOC
## GET Obter Mídia

### Description
Retrieves media using its ID and an optional phone number identifier. Supports streaming binary data by appending `&mode=stream`.

### Method
GET

### Endpoint
`/api/v1/media/get?id={media_id}&from={phone_number_id}`

### Parameters
#### Query Parameters
- **id** (string) - Required - The ID of the media to retrieve.
- **from** (string) - Optional - The identifier of the number that received the media. Recommended if managing multiple numbers.
- **mode** (string) - Optional - If set to `stream`, returns the binary file directly.

### Headers
- **X-API-Key** - Required - API Key for authentication.
- **X-API-Secret** - Required - API Secret for authentication.

### Response
#### Success Response (200)
- **media** (binary) - The requested media file if `mode=stream` is used.
- **(other fields)** - Details about the media if not streaming.
```

--------------------------------

### Webhook Signature Validation

Source: https://api.covercut.com.br/docs/index.php

Validate webhook signatures using the `X-BSP-Signature` header to ensure message authenticity. An example using PHP is provided.

```APIDOC
### Validar Assinatura (Segurança)

Cada envio contém o header `X-BSP-Signature`. Use-o para garantir que a mensagem veio de nós.

PHP — Validação de Assinatura
```
$signature = hash_hmac('sha256', $payload_bruto, $webhook_secret);
if (hash_equals($_SERVER['HTTP_X_BSP_SIGNATURE'], $signature)) {
    // Autêntico
}
```
```

--------------------------------

### Send Full Catalog Message

Source: https://api.covercut.com.br/docs/index.php

Use this endpoint to send a button that opens the business's complete catalog on WhatsApp. The `thumbnail_product_retailer_id` parameter is optional and specifies which product appears as the cover.

```json
{
  "from": "123456789012345",
  "to": "5547999999999",
  "type": "catalog_message",
  "body": {
    "text": "Confira todo o nosso catálogo com preços e disponibilidade em tempo real! 🛒"
  },
  "footer": {
    "text": "Entrega para todo o Brasil"
  },
  "action": {
    "name": "catalog_message",
    "parameters": {
      "thumbnail_product_retailer_id": "SKU_CAPA"
    }
  }
}
```

```json
{
  "from": "123456789012345",
  "recipient": "BR.13491208655302741918",
  "type": "catalog_message",
  "body": {
    "text": "Confira todo o nosso catálogo com preços e disponibilidade em tempo real! 🛒"
  },
  "footer": {
    "text": "Entrega para todo o Brasil"
  },
  "action": {
    "name": "catalog_message",
    "parameters": {
      "thumbnail_product_retailer_id": "SKU_CAPA"
    }
  }
}
```

--------------------------------

### Enviar Mensagem com Botão de URL (CTA URL)

Source: https://api.covercut.com.br/docs/index.php

Envia uma mensagem interativa com um botão que abre um link externo. Este recurso substitui a necessidade de templates para links simples.

```APIDOC
## POST /api/v1/messages/send (CTA URL)

### Description
Sends an interactive message with a button that opens an external link. This feature replaces the need for templates for simple links.

### Method
POST

### Endpoint
/api/v1/messages/send

### Parameters
#### Request Body
```json
{
  "from": "string",
  "to": "string",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "header": {
      "type": "text",
      "text": "string"
    },
    "body": {
      "text": "string"
    },
    "footer": {
      "text": "string"
    },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "string",
        "url": "string"
      }
    }
  }
}
```

### Request Example
```json
{
  "from": "123456789012345",
  "to": "5547999999999",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "header": {
      "type": "text",
      "text": "Confira nosso site"
    },
    "body": {
      "text": "Clique no botão abaixo para ver as ofertas exclusivas que preparamos para você hoje."
    },
    "footer": {
      "text": "Ofertas válidas por tempo limitado"
    },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "Ver Ofertas",
        "url": "https://sua-loja.com.br/ofertas"
      }
    }
  }
}
```

### Notes
- The `display_text` of the button accepts a maximum of 20 characters.
- The header is optional and accepts `text`, `image`, `video`, or `document`.
- This message type does not require prior approval from Meta.
```

```APIDOC
## POST /api/v1/messages/send (CTA URL by BSUID)

### Description
Sends an interactive message with a CTA URL button using the recipient's BSUID.

### Method
POST

### Endpoint
/api/v1/messages/send

### Parameters
#### Request Body
```json
{
  "from": "string",
  "recipient": "string",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "header": {
      "type": "text",
      "text": "string"
    },
    "body": {
      "text": "string"
    },
    "footer": {
      "text": "string"
    },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "string",
        "url": "string"
      }
    }
  }
}
```

### Request Example
```json
{
  "from": "123456789012345",
  "recipient": "BR.13491208655302741918",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "header": {
      "type": "text",
      "text": "Confira nosso site"
    },
    "body": {
      "text": "Clique no botão abaixo para ver as ofertas exclusivas que preparamos para você hoje."
    },
    "footer": {
      "text": "Ofertas válidas por tempo limitado"
    },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "Ver Ofertas",
        "url": "https://sua-loja.com.br/ofertas"
      }
    }
  }
}
```

### Notes
- The `display_text` of the button accepts a maximum of 20 characters.
- The header is optional and accepts `text`, `image`, `video`, or `document`.
- This message type does not require prior approval from Meta.
```

--------------------------------

### Webhook Payload Example: New Message

Source: https://api.covercut.com.br/docs/index.php

This JSON object represents the structure of a new inbound message event received via webhook.

```json
{
  "event": "message",
  "direction": "inbound",
  "contact": {
    "wa_id": "5547999999999",
    "user_id": "BR.13491208655302741918",
    "name": "João Silva"
  },
  "message": {
    "id": "wamid...",
    "type": "text",
    "text": "Oi!"
  }
}
```

--------------------------------

### Business-Scoped User IDs (BSUID) Transition

Source: https://api.covercut.com.br/docs/index.php

Details on the transition to using Business-Scoped User IDs (BSUID) as the primary identifier for users, starting July 2026.

```APIDOC
## Business-Scoped User IDs (BSUID) - July 2026 Onwards

### Description
Starting July 1, 2026, Meta will discontinue sending messages by phone number. All webhooks will include `from_user_id` (BSUID) as the primary identifier. Systems must be prepared to receive messages using only BSUID.

### What is BSUID?
BSUID (Business-Scoped User ID) is a unique identifier generated by Meta for each user-business pair. Format: `CC.xxxxx` (e.g., `BR.5519999999999`) or a WhatsApp username (e.g., `joao.silva`).

### Webhook Structure with BSUID (July 2026+)
```json
{
  "event": "message",
  "direction": "inbound",
  "contact": {
    "user_id": "BR.13491208655302741918",
    "username": "joao.silva",
    "name": "João Silva"
  },
  "message": {
    "id": "wamid...",
    "type": "text",
    "text": "Oi, tudo bem?"
  }
}
```

### Transition (June 2026) - Dual Mode
During the transition period, webhooks will include both the phone number and BSUID. Your system can choose which to use.

**Example - Message with Number + BSUID:**
```json
{
  "event": "message",
  "direction": "inbound",
  "contact": {
    "wa_id": "5547999999999",      
    "user_id": "BR.xxxxx",          
    "username": "joao.silva",       
    "name": "João Silva"
  },
  "message": { ... }
}
```

### Implementation Recommendations
- **Use BSUID as primary identifier**: If `user_id` is present, use it. Fallback to `wa_id` only if BSUID is not available.
- **Store username**: Capture and display the `username` when available for new contacts.
- **Support both**: Until July 2026, support receiving both fields. Do not remove support for phone numbers prematurely.
- **Test before July**: Activate BSUID in your Meta Developer Console to test webhooks WITHOUT the phone number.
```

--------------------------------

### Enviar Carrossel de Mídia Interativo

Source: https://api.covercut.com.br/docs/index.php

Crie mensagens interativas com carrosséis horizontais contendo de 2 a 10 cartões. Cada cartão pode ter um cabeçalho de imagem ou vídeo, texto no corpo e um botão de URL ou resposta rápida. O tipo e a quantidade de botões devem ser consistentes em todos os cartões.

```http
POST https://api.covercut.com.br/api/v1/messages/carousel
```

--------------------------------

### POST Criar Grupo

Source: https://api.covercut.com.br/docs/index.php

Creates a new WhatsApp group and sets its initial configurations.

```APIDOC
## POST Criar Grupo

### Description
Creates a new group on WhatsApp and sets the initial configurations.

### Method
POST

### Endpoint
`/api/v1/groups/create`

### Parameters
#### Request Body
- **from** (string) - Optional - The phone number ID from which to create the group.
- **subject** (string) - Required - The name of the group.
- **description** (string) - Optional - The description of the group.
- **join_approval_mode** (string) - Required - Specifies the join approval mode. Accepted values: `auto_approve` or `approval_required`.

### Request Example
```json
{
  "from": "PHONE_NUMBER_ID",
  "subject": "Nome do Grupo",
  "description": "Descrição do grupo (opcional)",
  "join_approval_mode": "auto_approve"
}
```

### Response
#### Success Response (200)
- **group_lifecycle_update** (object) - Contains information about the group lifecycle, including the invite link.
  - **invite_link** (string) - The link to invite users to the group.
```

--------------------------------

### GET Exportar Logs (CSV)

Source: https://api.covercut.com.br/docs/index.php

Generates and downloads a complete CSV file containing message history, facilitating import into BI, ERP, or CRM tools for self-retention.

```APIDOC
## GET /api/v1/messages/export

### Description
Generate and download a complete .csv file containing the message history, facilitating import into BI, ERP, or CRM tools for your own retention.

### Method
GET

### Endpoint
/api/v1/messages/export

### Parameters
#### Query Parameters
- **wamid** (string) - Optional - Unique message ID (WAID).
- **status** (string) - Optional - Filters by: `sent`, `delivered`, `read`, or `failed`.
- **limit** (integer) - Optional - Quantity per page (Default 50, Max 100).
- **since** (string) - Optional - Start date. Format YYYY-MM-DD (e.g., 2026-05-01).
- **until** (string) - Optional - End date. Format YYYY-MM-DD (e.g., 2026-05-31).
- **from** (string) - Optional - Filters by the origin number that sent the message.
- **recipient** (string) - Optional - Filters by the destination phone number.

### Response
#### Success Response (200 OK)
- **success** (boolean) - Indicates if the operation was successful.
- **messages** (array) - A list of message objects.
  - **wamid** (string) - Unique message ID (WAID).
  - **status** (string) - The status of the message (e.g., `sent`, `delivered`, `read`, `failed`).
  - **recipient** (string) - The recipient's phone number.
  - **created_at** (string) - The timestamp when the message was created.

### Response Example
```json
{
  "success": true,
  "messages": [
    {
      "wamid": "wamid.HBgLNTUxMTk5OTk5OTk5...",
      "status": "read",
      "recipient": "5511999990000",
      "created_at": "2025-01-10 14:32:00"
    }
  ]
}
```
```

--------------------------------

### Get Group Information

Source: https://api.covercut.com.br/docs/index.php

Retrieves detailed information about a specific group, including subject, description, participants, and approval mode. Requires the group ID and a phone number ID.

```http
GET /api/v1/groups/info?group_id=GROUP_ID&from=PHONE_NUMBER_ID
```

--------------------------------

### GET Consultar Status da Mensagem

Source: https://api.covercut.com.br/docs/index.php

Queries the delivery status of messages sent from your number. Use this endpoint to synchronize `sent`, `delivered`, `read`, and `failed` statuses with your database.

```APIDOC
## GET /api/v1/messages/status

### Description
Consult the delivery status of messages sent from your number. Use this endpoint to synchronize `sent`, `delivered`, `read`, and `failed` statuses with your database.

### Method
GET

### Endpoint
`/api/v1/messages/status`

### Request Example
```
GET https://api.covercut.com.br/api/v1/messages/status
```

### Response
(Response details not provided in the source text)
```

--------------------------------

### Create Order Details Template

Source: https://api.covercut.com.br/docs/index.php

Define a template with the 'ORDER_DETAILS' display format to showcase order items, subtotals, taxes, and payment options. This template is suitable for invoices and detailed charges.

```json
{
  "from": "123456789012345",
  "name": "fatura_detalhada",
  "category": "UTILITY",
  "language": "pt_BR",
  "display_format": "ORDER_DETAILS",
  "components": [
    {
      "type": "HEADER",
      "format": "DOCUMENT",
      "text": "Sua Fatura"
    },
    {
      "type": "BODY",
      "text": "Olá, {{1}}! Segue sua fatura. Escolha a forma de pagamento."
    },
    {
      "type": "BUTTONS",
      "buttons": [
        { "type": "ORDER_DETAILS", "text": "Ver detalhes do pedido" }
      ]
    }
  ]
}
```

--------------------------------

### Query Message Status

Source: https://api.covercut.com.br/docs/index.php

Use this GET endpoint to check the delivery status of messages sent from your number. This is useful for synchronizing `sent`, `delivered`, `read`, and `failed` statuses with your database.

```http
GET https://api.covercut.com.br/api/v1/messages/status
```

--------------------------------

### Enviar Mensagem com Botão de URL (CTA)

Source: https://api.covercut.com.br/docs/index.php

Envie uma mensagem interativa com um botão de Call-to-Action (CTA) que abre um link externo. O 'display_text' do botão tem um limite de 20 caracteres. O cabeçalho é opcional e pode ser de texto, imagem, vídeo ou documento.

```json
{
  "from": "123456789012345",
  "to": "5547999999999",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "header": { "type": "text", "text": "Confira nosso site" },
    "body": { "text": "Clique no botão abaixo para ver as ofertas exclusivas que preparamos para você hoje." },
    "footer": { "text": "Ofertas válidas por tempo limitado" },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "Ver Ofertas",
        "url": "https://sua-loja.com.br/ofertas"
      }
    }
  }
}
```

```json
{
  "from": "123456789012345",
  "recipient": "BR.13491208655302741918",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "header": { "type": "text", "text": "Confira nosso site" },
    "body": { "text": "Clique no botão abaixo para ver as ofertas exclusivas que preparamos para você hoje." },
    "footer": { "text": "Ofertas válidas por tempo limitado" },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "Ver Ofertas",
        "url": "https://sua-loja.com.br/ofertas"
      }
    }
  }
}
```