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": "5511888888888@s.whatsapp.net",
      "lid": "LID123@lid",
      "name": "John Doe (Updated)",
      "profilePictureUrl": "https://new-picture-url...",
      "isBusiness": false
    },
    "updatedFields": ["name", "profilePictureUrl"],
    "instanceId": "instance-uuid",
    "connectedNumber": "5511999999999",
    "timestamp": "2024-12-14T12:00:00.000Z"
  }
}

Data Fields

Field	Type	Description
contact	object	Updated contact information
updatedFields	array	List of fields that were updated
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 (phone@s.whatsapp.net)
lid	string | null	WhatsApp LID (local identifier)
name	string | null	Contact name
profilePictureUrl	string | null	Profile picture URL
isBusiness	boolean | undefined	Whether this is a WhatsApp Business account

Updated Fields

The updatedFields array contains the names of fields that changed:

Field	Description
name	Contact name was updated
profilePictureUrl	Profile picture changed
jid	JID was added or changed
lid	LID was added or changed

Common Update Scenarios

Name Change

User changed their WhatsApp display name:

{
  "updatedFields": ["name"],
  "contact": {
    "name": "New Display Name"
  }
}

Profile Picture Update

User changed their profile picture:

{
  "updatedFields": ["profilePictureUrl"],
  "contact": {
    "profilePictureUrl": "https://new-url..."
  }
}

LID to JID Mapping

WhatsApp revealed the phone number for a LID-only contact:

{
  "updatedFields": ["jid"],
  "contact": {
    "lid": "LID123@lid",
    "jid": "5511888888888@s.whatsapp.net"
  }
}

Example: Handling Updates

app.post('/webhook', async (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'contact-updated') {
    const { contact, updatedFields } = data;
    
    // Build update object with only changed fields
    const updates = {};
    
    if (updatedFields.includes('name')) {
      updates.name = contact.name;
    }
    if (updatedFields.includes('profilePictureUrl')) {
      updates.profilePicture = contact.profilePictureUrl;
    }
    if (updatedFields.includes('jid')) {
      updates.phoneNumber = contact.jid?.replace('@s.whatsapp.net', '');
    }
    
    // Update in your database
    await db.contacts.update(
      { externalId: contact.id },
      updates
    );
    
    console.log(`Contact ${contact.id} updated: ${updatedFields.join(', ')}`);
  }
  
  res.status(200).send('OK');
});