Important differences in using a lid instead of a telephone number#

WhatsApp is phasing out phone numbers as chat identifiers. We're proactively creating the conditions for working with our API. The architecture and logic for interacting with the API remain the same, but there are a few differences in how the messenger handles contacts.

WhatsApp's changes will affect all users, so it's important to be prepared for the changes. In this article, we'll look at the API changes and what you need to do to continue using the WhatsApp API effectively while maintaining your customer experience.

Contents#

• How messages were previously sent by phone number
• Phasing out the @c.us prefix
• Send messages by @lid
• Receiving journals and webhooks with @lid
• Changing a lid
• The need to switch to @lid

How messages were previously sent by phone number#

To send messages, use the Chat Id. GREEN-API supports two chat types: personal chat and group chat.

Previously, it was sufficient to specify the recipient's phone number with the @c.us prefix in the method's request body to send a text message:

    {
    "chatId": "1111111111@c.us",
    "message": "Hello, John Doe"
    }

Phasing out the @c.us prefix#

All message sending methods, chat ID, journals methods, and webhooks use the @c.us prefix for backward compatibility. You will now receive the chat ID as @lid instead.

We strongly recommend switching to using the @lid instead of a personal chat ID.

Send messages by @lid#

In general, sending messages via @lid differs from sending messages via phone number in that the lid must first be obtained from the user's conversation.

If the chat ID is unknown, please use the CheckWhatsapp method first, get the chatId value to send messages by SendMessage and other methods.

Sending a message using @lid

    {
    "chatId": "120650379300963@lid",
    "message": "Hello, John Doe"
    }

Currently, the user's phone number will be included in journals and webhooks, even if sent via @lid.

Receiving journals and webhooks with @lid#

In your account, set the Use chat IDs field to yes in your instance settings, then click Save Changes. Alternatively, use the SetSettings method and set the EnableLidMode field to yes.

To apply the settings, you need to log out of your instance and then re-authorize it using a QR code or code. To receive journals and webhooks, enable notifications in your account or use the SetSettings method.

Verify that the instance settings have been applied using the GetSettings method. To do this, check that the EnableLidMode field - yes.

If all settings are applied, the chatId and senderId fields in the journal will contain the @lid number, unique for each instance.

Example journal for recent incoming messages with @lid

{
        "type": "incoming",
        "idMessage": "ACB2EA51BD0573D8F64E480908C6017A",
        "timestamp": 1779704763,
        "typeMessage": "textMessage",
        "chatId": "155508384256027@lid",
        "textMessage": "Hi, I'm using GREEN-API to send a message on WhatsApp!",
        "senderId": "155508384256027@lid",
        "senderName": "John Doe",
        "senderContactName": "",
        "deletedMessageId": "",
        "editedMessageId": "",
        "isEdited": false,
        "isDeleted": false
    },
    {
        "type": "incoming",
        "idMessage": "AC710B072D589F5583ADF9E4C904330E",
        "timestamp": 1779703495,
        "typeMessage": "textMessage",
        "chatId": "155508384256027@lid",
        "textMessage": "Hi! I'm using GREEN-API!",
        "senderId": "155508384256027@lid",
        "senderName": "John Doe",
        "senderContactName": "",
        "deletedMessageId": "",
        "editedMessageId": "",
        "isEdited": false,
        "isDeleted": false
    }

Example of an incoming message webhook with @lid

{
  "typeWebhook": "incomingMessageReceived",
  "idMessage": "AC162054DB255E4CF2FBD5C559089191",
  "instanceData": {
    "idInstance": 1101111111,
    "wid": "79876543210@c.us",
    "typeInstance": "whatsapp"
  },
  "timestamp": 1588091580,
  "senderData": {
    "chatId": "155508384256027@lid",
    "sender": "155508384256027@lid",
    "senderName": "John",
    "senderContactName": "",
    "chatName": "John Doe"
  },
  "messageData": {
    "typeMessage": "textMessage",
    "textMessageData": {
      "textMessage": "Hi, I'm using GREEN-API to send a message on WhatsApp!"
    }
  }
}

Changing a lid#

In rare cases, a chat can move from one lid to another. This does not happen often: on an account with 100 chats, it may affect one chat.

A lid change occurs on the messenger side and is not related to:

• a change of the user's phone number;
• transferring an account between Meta Business Manager and WhatsApp;
• any actions of the user or of your integration.

WhatsApp notifies us about the identifier change, and we store the new lid on our side. The new identifier is returned by the GetChats and GetContacts methods in the newChatId field.

The newChatId field is included in the response only when a new lid is already available for the user. If there is no new lid, the field will not be in the response.

Example of the GetContacts method response with a new lid

[
    {
        "id": "138788093320001@lid",
        "name": "John Doe",
        "contactName": "John Doe Work",
        "type": "user",
        "newChatId": "138788093320002@lid"
    }
]

Example of the GetChats method response with a new lid

[
    {
        "archive": false,
        "id": "138788093320001@lid",
        "ephemeralExpiration": 0,
        "ephemeralSettingTimestamp": 0,
        "name": "John Doe",
        "type": "user",
        "unreadCount": 0,
        "newChatId": "138788093320002@lid"
    }
]

The need to switch to @lid#

WhatsApp has announced that the gradual phase-out of phone numbers will continue until approximately the end of 2026, so it's important to be prepared for changes.

This article has shown that the transition to @lid can be accomplished quickly and without significant changes in integration.

That's why it's a good idea to prepare your integration or chatbot for @lid today.