WhatsApp — message/sendContacts

When to Use

Agent introduction: A customer support workflow sends the assigned support agent's contact card (name, direct phone, email) to a customer when their case is escalated to a named agent.
Referral sharing: A sales workflow sends a referral contact card to a customer after they agree to refer a friend, making it easy for them to share the sales rep's details.
Supplier contact distribution: A procurement workflow sends a new supplier's contact card to the relevant team members when a new supplier is approved in the system.
Emergency contact dispatch: An incident management workflow sends the on-call engineer's contact card to a customer when a critical issue is escalated, enabling direct communication.
Digital business card campaigns: A marketing workflow sends the company's WhatsApp Business contact card to new leads who scan a QR code at trade shows, enabling one-tap saves.

Configuration

Connection

Field	Required	Description
`accessToken`	Required	Permanent System User access token. Store in BizFirst Credentials Manager.
`phoneNumberId`	Required	Numeric string ID of the sending WhatsApp Business phone number.
`apiVersion`	Optional	Meta Graph API version. Defaults to `v18.0`.

Operation

Field	Required	Description
`to`	Required	Recipient's phone number with country code, no + prefix (e.g. `14155552671`).
`contactsJson`	Required	A JSON array string of contact objects conforming to the WhatsApp contact schema. Each contact must have at minimum a `name` object with a `formatted_name` field. See the schema below.

Contact Object Schema

Each object in the contactsJson array supports the following fields:

Field	Required	Description
`name.formatted_name`	Required	Full display name for the contact (e.g. `"Jane Smith"`).
`name.first_name`	Optional	First name component.
`name.last_name`	Optional	Last name component.
`phones`	Optional	Array of phone objects: `{ "phone": "+14155552671", "type": "CELL", "wa_id": "14155552671" }`. Type options: CELL, MAIN, IPHONE, HOME, WORK.
`emails`	Optional	Array of email objects: `{ "email": "jane@example.com", "type": "WORK" }`.
`org`	Optional	Organisation object: `{ "company": "Acme Corp", "title": "Sales Manager" }`.
`urls`	Optional	Array of URL objects: `{ "url": "https://example.com", "type": "WORK" }`.

Sample Configuration

{
  "resource": "message",
  "operation": "sendContacts",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "123456789012345",
  "to": "{{ $input.customerPhone }}",
  "contactsJson": "[{\"name\":{\"formatted_name\":\"{{ $input.agentName }}\",\"first_name\":\"{{ $input.agentFirstName }}\",\"last_name\":\"{{ $input.agentLastName }}\"},\"phones\":[{\"phone\":\"{{ $input.agentPhone }}\",\"type\":\"WORK\",\"wa_id\":\"{{ $input.agentWaId }}\"}],\"emails\":[{\"email\":\"{{ $input.agentEmail }}\",\"type\":\"WORK\"}],\"org\":{\"company\":\"BizFirst Support\",\"title\":\"{{ $input.agentTitle }}\"}}]"
}

Validation Errors

Error	Cause
`accessToken is required`	The `accessToken` field is empty.
`phoneNumberId is required`	The `phoneNumberId` field is empty.
`to is required`	The `to` field is empty.
`Invalid JSON in contacts: ...`	The `contactsJson` string is not valid JSON. Validate with a Function node before passing to this operation.
`131047` (Meta)	24-hour customer service window expired.
`131026` (Meta)	Recipient is not a registered WhatsApp user.

Output

Success Port

Field	Type	Description
`messageId`	string	Unique WhatsApp message ID (wamid).
`phoneNumberId`	string	The sending phone number ID.
`to`	string	The recipient phone number.
`status`	string	`"sent"` on success.
`errorCode`	string	Empty on success.
`errorMessage`	string	Empty on success.
`rawResponse`	string	Full raw JSON from the Meta API.

Error Port

Field	Type	Description
`status`	string	`"failed"` or `"error"`.
`errorCode`	string	Meta error code or BizFirst validation code.
`errorMessage`	string	Human-readable error description.
`rawResponse`	string	Raw API error response.

Sample Output

{
  "messageId": "wamid.HBgLMTQxNTU1NTI2NzEVAgARGBI0QzM4NjhGQTExMjQ3RDMAA",
  "phoneNumberId": "123456789012345",
  "to": "14155552671",
  "status": "sent",
  "errorCode": null,
  "errorMessage": null,
  "rawResponse": "{\"messaging_product\":\"whatsapp\",\"contacts\":[{\"input\":\"14155552671\",\"wa_id\":\"14155552671\"}],\"messages\":[{\"id\":\"wamid.HBgLMTQxNTU1NTI2NzEVAgARGBI0QzM4NjhGQTExMjQ3RDMAA\"}]}"
}

Expression Reference

Value	Expression	Notes
Message ID	`{{ $output.sendContact.messageId }}`	Retain for audit trail.
Recipient	`{{ $output.sendContact.to }}`	For confirmation logging.
Status	`{{ $output.sendContact.status }}`	Branch on outcome in IfCondition.

Node Policies & GuardRails

Policy Area	Recommendation
Credential storage	Store the access token in BizFirst Credentials Manager. Never inline in configuration.
JSON validation	Always validate the `contactsJson` string in a Function node before passing it to this operation. Invalid JSON fails with a BizFirst-level error before reaching Meta, which is preferable to a runtime exception but validation ensures consistent failure messages.
PII handling	Contact records contain personal information. Only send contacts to users who have a legitimate need to receive them. Log all sends in your audit trail with the operator's identity.
Consent	Ensure the person whose contact card you are sharing has consented to having their phone number and email distributed via WhatsApp. This is especially important for employee contacts shared in commercial workflows.
24-hour window	Contact messages are free-form. Outside the customer service window, re-engage with a template message first.
Error port	Connect the error port. JSON parse failures surface here with a clear `invalid_json` error code and should be routed to a validation error handling branch.

Examples

Support Agent Contact Card on Case Escalation

{
  "resource": "message",
  "operation": "sendContacts",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "123456789012345",
  "to": "{{ $input.customerPhone }}",
  "contactsJson": "[{\"name\":{\"formatted_name\":\"Sarah Johnson\",\"first_name\":\"Sarah\",\"last_name\":\"Johnson\"},\"phones\":[{\"phone\":\"+14155559876\",\"type\":\"WORK\",\"wa_id\":\"14155559876\"}],\"emails\":[{\"email\":\"sarah.johnson@example.com\",\"type\":\"WORK\"}],\"org\":{\"company\":\"BizFirst Support\",\"title\":\"Senior Support Specialist\"}}]"
}

After a support case is escalated, this node sends the assigned agent's contact card. The customer can tap "Add to Contacts" and directly message or call the agent using WhatsApp.

Multiple Contact Cards for a Team

{
  "resource": "message",
  "operation": "sendContacts",
  "accessToken": "{{ $credentials.whatsAppToken }}",
  "phoneNumberId": "123456789012345",
  "to": "{{ $input.newEmployeePhone }}",
  "contactsJson": "[{\"name\":{\"formatted_name\":\"IT Helpdesk\"},\"phones\":[{\"phone\":\"+14155551234\",\"type\":\"WORK\"}],\"emails\":[{\"email\":\"it@example.com\",\"type\":\"WORK\"}]},{\"name\":{\"formatted_name\":\"HR Department\"},\"phones\":[{\"phone\":\"+14155555678\",\"type\":\"WORK\"}],\"emails\":[{\"email\":\"hr@example.com\",\"type\":\"WORK\"}]}]"
}

An onboarding workflow sends two contact cards — IT Helpdesk and HR — to a new employee on their first day. The array-based format allows multiple contacts in a single message that the recipient can selectively save.