Endpoint
Authentication
Include your project API password in every request header:Path Parameters
string
required
Your Convo project ID. You can find this in your Convo dashboard under Project Settings.
Request Body
string
required
The contact’s display name as it will appear in your Convo dashboard and in conversations.
string
required
The contact’s WhatsApp phone number including the country code. Do not include a leading
+ sign. Example: 917089379345 for an Indian number (+91 70893 79345).Example Request
Response
200 OK — Returns the full contact object for the newly created contact.Response Fields
string
The Convo-assigned unique ID for this contact. Use this ID with the Get Contact, Update Contact, and messaging endpoints.
string
The Convo project this contact belongs to.
string
The contact’s WhatsApp phone number (with country code, no
+).string
The contact’s display name as provided during creation.
string
The numeric country dialing code extracted from the phone number (e.g.,
"91" for India).boolean
true if the phone number is registered on WhatsApp. Convo verifies this automatically when the contact is created.boolean
true if the conversation with this contact has been marked as closed in the Convo inbox.boolean
true if a human agent has taken over this contact’s conversation from the bot or automation.boolean
true if the contact has an active pending request awaiting a human agent response.number
Unix timestamp in milliseconds of the contact’s most recent activity.
array
List of tags applied to this contact. Empty array for newly created contacts.
object
Key-value map of custom attributes for this contact. Empty object for newly created contacts. Use Update Contact to populate custom attributes.
object
Object containing
id and added_at for the contact’s first inbound message. null if no messages have been received yet.number
Unix timestamp in milliseconds when the contact was created.