> For the complete documentation index, see [llms.txt](https://docs.lipachat.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lipachat.com/api/request-a-whatsapp-users-phone-number.md).

# Request a WhatsApp user's phone number

Use this endpoint to send a WhatsApp interactive message that asks the recipient to share their contact information. The recipient can be addressed by phone number or by a Business-Scoped User ID (BSUID).

This endpoint sends an interactive `request_contact_info` message. It is intended for an active customer service conversation window; Meta may reject it if the conversation is outside that window.

### Endpoint

```http
POST /api/v1/whatsapp/request_contact_info
```

#### Headers

| Header         | Required | Description        |
| -------------- | -------- | ------------------ |
| `apiKey`       | Yes      | Lipachat API key.  |
| `Content-Type` | Yes      | `application/json` |

#### Request body

| Field       | Type   | Required | Description                                                |
| ----------- | ------ | -------- | ---------------------------------------------------------- |
| `messageId` | string | Yes      | Your unique ID for this request.                           |
| `from`      | string | Yes      | The business WhatsApp phone number registered in Lipachat. |
| `to`        | string | Yes      | Recipient's phone number or BSUID.                         |
| `text`      | string | Yes      | Text displayed with the contact request button.            |

#### Example request

```bash
curl --request POST 'https://<LIPACHAT_API_HOST>/api/v1/whatsapp/request_contact_info' \
  --header 'apiKey: <LIPACHAT_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "messageId": "contact-request-001",
    "from": "+254700000000",
    "to": "KE.13491208655302741918",
    "text": "Please share your phone number so we can contact you."
  }'
```

When `to` is a BSUID, Lipachat sends it to Meta in the `recipient` field. For a phone number, Lipachat uses Meta's `to` field.

#### Success response

The API returns HTTP `201 Created` when the request is accepted by Meta.

```json
{
  "timestamp": "2026-10-09T12:00:00",
  "data": {
    "messageId": "contact-request-001",
    "waId": "wamid.HBg...",
    "status": "SENT",
    "statusDesc": "Contact info request sent successfully"
  },
  "status": "success",
  "message": ""
}
```

`SENT` means Meta accepted the send request. The recipient's response arrives separately through the configured inbound message callback.

### Contact-sharing callback

When the recipient shares a contact, Lipachat sends the configured client webhook a normalized message payload with `type: "CONTACTS"`. It does not forward Meta's full `object` / `entry` / `changes` envelope.

```json
{
  "messageId": "wamid.HBg...",
  "from": "KE.13491208655302741918",
  "from_user_id": "KE.13491208655302741918",
  "to": "+254700000000",
  "profileName": "Amina",
  "type": "CONTACTS",
  "contacts": [
    {
      "vcard": "BEGIN:VCARD\nVERSION:3.0\n...",
      "origin": "<ORIGIN_VALUE_FROM_META>",
      "phones": [
        {
          "phone": "+254711111111",
          "wa_id": "254711111111",
          "type": "CELL"
        }
      ]
    }
  ]
}
```

#### Callback fields

| Field               | Description                                                                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------- |
| `messageId`         | WhatsApp message ID for the contact-sharing message.                                                      |
| `from`              | Sender address. This may be a phone number or BSUID.                                                      |
| `from_user_id`      | Sender's BSUID when Meta supplies it. Use this to identify the sender when a phone number is unavailable. |
| `to`                | Business WhatsApp phone number that received the message.                                                 |
| `profileName`       | Sender profile name; Lipachat uses the profile username as a fallback when a name is unavailable.         |
| `type`              | `CONTACTS` for a shared contact message.                                                                  |
| `contacts[].vcard`  | vCard content returned by Meta.                                                                           |
| `contacts[].origin` | Origin value returned by Meta for the shared contact.                                                     |
| `contacts[].phones` | Phone numbers included in the shared contact, including `wa_id` and `type` when provided.                 |

The `from_user_id` field is optional because Meta may omit it. The `vcard`, `origin`, and phone fields depend on what Meta includes in the incoming message.