Contact Updated Event

Triggered when a contact's information is updated. This includes changes to name, profile picture, or identifier mappings (JID/LID).

Event Type

contact-updated

Payload Structure

{
  "event": "contact-updated",
  "instanceId": "instance-uuid",
  "data": {
    "contact": {
      "id": "contact-uuid",
      "jid": "[email protected]",
      "lid": "LID123@lid",
      "name": "John Doe (Updated)",
      "profilePictureUrl": "https://new-picture-url...",
      "isBusiness": false
    },
    "instanceId": "instance-uuid",
    "connectedNumber": "5511999999999",
    "timestamp": "2024-12-14T12:00:00.000Z"
  }
}

Data Fields

Field	Type	Description
contact	object	Updated contact information
instanceId	string	Instance ID
connectedNumber	string	Connected phone number
timestamp	string	ISO 8601 timestamp of the event

Contact Object

Field	Type	Description
id	string	Internal contact ID
jid	string | null	WhatsApp JID ([email protected])
lid	string | null	WhatsApp LID (local identifier) - primary identifier
name	string | null	Contact name
profilePictureUrl	string | null	Profile picture URL
isBusiness	boolean | undefined	Whether this is a WhatsApp Business account

Common Update Scenarios

Name Change

User changed their WhatsApp display name.

Profile Picture Update

User changed their profile picture.

LID to JID Mapping Discovery

WhatsApp revealed the phone number for a LID-only contact. This is a common scenario when:

1. A contact initially only had a LID (privacy-preserving identifier)
2. WhatsApp later maps the LID to a phone number (JID)
3. The contact is updated with both identifiers

{
  "contact": {
    "lid": "LID123@lid",
    "jid": "[email protected]",
    "name": "Contact Name"
  }
}

Understanding JID and LID

WhatsApp uses two types of identifiers:

• LID (Local ID): The newer, primary identifier used by WhatsApp. LID is prioritized in ZapyAPI.
• JID (Jabber ID): The traditional identifier based on phone number (e.g., [email protected]).

LID Priority

LID is the primary identifier in ZapyAPI. When WhatsApp reveals a phone number for a LID-only contact, both identifiers will be available in the updated contact.

Example: Handling Updates

app.post('/webhook', async (req, res) => {
  const { event, data } = req.body;

  if (event === 'contact-updated') {
    const { contact } = data;

    // Update in your database using the stable contact ID
    await db.contacts.update(
      { externalId: contact.id },
      {
        name: contact.name,
        profilePicture: contact.profilePictureUrl,
        phoneNumber: contact.jid?.replace('@s.whatsapp.net', ''),
        lid: contact.lid,
        isBusiness: contact.isBusiness
      }
    );

    console.log(`Contact ${contact.id} updated: ${contact.name}`);
  }

  res.status(200).send('OK');
});