Developers

ManyContacts API

Integrate WhatsApp into your applications: send messages, manage contacts and receive real-time events through webhooks. A simple REST API over HTTPS that returns JSON.

Get your API key View OpenAPI spec

Authentication

All calls are made over HTTPS against the API base URL. Responses are returned as JSON.

Base URL: https://api.manycontacts.com

Authentication uses an apikey HTTP header with your organization's key. Every request must include this header.

curl https://api.manycontacts.com/v1/contacts \
  -H "apikey: TU_API_KEY"

Find (and regenerate) your API key in the app: Settings → Developers. The key is not available during the trial period.

Rate limits

Requests are limited per organization within a 60-second window, based on your plan:

Plan	Limit
Paid account	60 req / min
Free / trial account	10 req / min

When you exceed the limit, the API responds with a 429 status. The TTL field shows the seconds left before you can retry.

HTTP/1.1 429 Too Many Requests
{ "error": "Too many requests. Try again after sometime or contact support@manycontacts.com. TTL42" }

Errors and status codes

The API uses standard HTTP status codes. Newer endpoints also return a JSON body with an error field (and, when relevant, detail).

Code	Meaning
`200`	Success. The operation completed.
`400`	Bad request: missing or invalid parameters.
`401`	Unauthorized: the apikey header is missing or invalid.
`402`	Payment required: no AI credits available.
`404`	Not found: the requested resource does not exist.
`422`	Unprocessable: the operation isn't possible in the current state (e.g. unsupported gateway).
`429`	Too many requests: the rate limit has been exceeded.
`500`	Internal server error.

Older endpoints may return a status code without a JSON body. When the message is sent but the provider (Meta) returns a warning, the response is 200 with the detail inside the error field.

Messages

Send WhatsApp messages to your contacts. You can identify the contact by phone number or by ID.

POST `/v1/message/text`

Sends a text message. If the contact doesn't exist, it is created automatically.

Parameter	Type	Required	Description
`text`	string	Yes	Message body.
`number`	string	Conditional	Contact phone in international format, without the '+' sign. Required if contactid is not provided.
`contactid`	string	Conditional	Contact ID (UUID). Alternative to number.
`conchi_user_id`	string	No	ID of an AI user in the organization, to attribute the message to that agent.

Example request

curl -X POST https://api.manycontacts.com/v1/message/text \
  -H "apikey: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "number": "34600111222", "text": "Hola 👋" }'

Example response

{ "id": "8f3c...", "error": null }

POST `/v1/message/media`

Sends a file (image, audio, video or document) as a multipart attachment. The type is detected from the file.

Parameter	Type	Required	Description
`number`	string	Yes	Contact phone in international format, without the '+' sign. Required if contactid is not provided.
`file`	file (multipart)	Yes	File to send (multipart/form-data).
`caption`	string	No	Text accompanying the file.

Example request

curl -X POST https://api.manycontacts.com/v1/message/media \
  -H "apikey: TU_API_KEY" \
  -F "number=34600111222" \
  -F "caption=Tu factura" \
  -F "file=@factura.pdf"

Example response

{ "id": "8f3c...", "error": null }

POST `/v1/message/note`

Adds an internal note to the contact's conversation (not sent to the customer).

Parameter	Type	Required	Description
`number`	string	Yes	Contact phone in international format, without the '+' sign. Required if contactid is not provided.
`text`	string	Yes	Note content.
`hidden`	boolean	No	If true, the note does not mark the conversation as pending.
`tagId`	string	No	ID of a tag to assign to the contact along with the note.

Example request

curl -X POST https://api.manycontacts.com/v1/message/note \
  -H "apikey: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "number": "34600111222", "text": "Cliente VIP, priorizar respuesta", "hidden": true }'

Example response

{
  "id": "3b1e...",
  "type": 2,
  "contact_id": "8f3c...",
  "timestamp": "2026-07-09T13:00:00.000Z",
  "text": "Cliente VIP, priorizar respuesta"
}

POST `/v1/message/interactive`

Sends an interactive message with quick-reply buttons or a list of options. Based on the number of buttons, ManyContacts automatically picks the right format.

Parameter	Type	Required	Description
`text`	string	Yes	Message body.
`buttons`	string[]	Yes	List of button titles (1 to 10). With 1-3 buttons, reply buttons are sent (max 20 chars); with 4-10, a list is generated (max 24 chars).
`number`	string	Conditional	Contact phone in international format, without the '+' sign. Required if contactid is not provided.
`contactid`	string	Conditional	Contact ID (UUID). Alternative to number.
`header`	string	No	Optional message header (max 60 chars).
`footer`	string	No	Optional message footer (max 60 chars).
`cta`	string	No	Text of the button that opens the list (list mode only, max 20 chars). Defaults to 'View options'.

Requires the organization to use WhatsApp API or WhatsApp Coexistence (Meta gateway) and the contact to have messaged within the last 24 hours (Meta service window).

Example request

curl -X POST https://api.manycontacts.com/v1/message/interactive \
  -H "apikey: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "34600111222",
    "text": "¿Confirmas tu cita?",
    "header": "Recordatorio",
    "footer": "Clínica ManyContacts",
    "buttons": ["Sí, confirmo", "Reprogramar", "Cancelar"]
  }'

Example response

{ "id": "8f3c...", "error": null }

Specific errors

Code	`error`	Meaning
`400`	`invalid_parameters`	Missing parameters or failed validations (empty text, button count out of range, exceeded lengths...).
`404`	`contact_not_found`	No contact exists with that number or ID.
`422`	`gateway_not_supported`	The organization does not have WhatsApp API or Coexistence enabled.
`422`	`outside_24h_window`	The contact is outside Meta's 24-hour window. Use a template to reopen the conversation.

Contacts (v1)

Manage your contacts by ID (UUID). Most actions that take a number auto-create the contact if it doesn't exist.

Note: endpoints that take a number auto-create the contact (source: 'api') if it doesn't exist.

Endpoints that return a contact use this shape (main fields):

{
  "id": "8f3c...",
  "name": "Juan",
  "email": null,
  "open": true,
  "last_user_id": null,
  "number": "34600111222",
  "notes": null,
  "locked": false,
  "customFields": {},
  "tags": [{ "id": "a1b2...", "name": "Cliente", "color": "#55efc4" }]
}

GET `/v1/contacts`

List of contacts with filters (assignment, page, closed, users, tags).

Parameter	Type	Required	Description
`filter`	integer (query)	No	0 = only unassigned and open chats; 1 = all chats.
`page`	integer (query)	No	Results page (50 per page, starting at 0).
`closed`	boolean (query)	No	If 'true', returns only closed conversations.
`users`	string[] (query)	No	Filter by assigned user IDs (repeatable parameter).
`tags`	string[] (query)	No	Filter by tag IDs; the contact must have all of them (repeatable parameter).

Example request

curl "https://api.manycontacts.com/v1/contacts?filter=1&page=0&closed=false" \
  -H "apikey: TU_API_KEY"

Example response

[
  {
    "id": "8f3c...",
    "name": "Juan",
    "email": null,
    "open": true,
    "last_user_id": null,
    "number": "34600111222",
    "notes": null,
    "locked": false,
    "customFields": {},
    "tags": []
  }
]

GET `/v1/contact/:id`

Get a contact by its ID.

Parameter	Type	Required	Description
`id`	string (path)	Yes	Contact ID (UUID), in the path.

Example request

curl https://api.manycontacts.com/v1/contact/8f3c... \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "open": true, "tags": [] }

GET `/v1/contact/phone/:phone`

Get a contact by phone number.

Parameter	Type	Required	Description
`phone`	string (path)	Yes	Contact phone in international format (digits only), in the path.

If no contact exists with that number, it returns an empty object { }.

Example request

curl https://api.manycontacts.com/v1/contact/phone/34600111222 \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "open": true, "tags": [] }

POST `/v1/contact`

Create a contact (or return the existing one). Requires number.

Parameter	Type	Required	Description
`number`	string	Yes	Contact phone in international format, without the '+' sign. Required if contactid is not provided.
`name`	string	No	Contact name.
`assigned`	string	No	ID of the user to assign the contact to on creation.

Example request

curl -X POST https://api.manycontacts.com/v1/contact \
  -H "apikey: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "number": "34600111222", "name": "Juan" }'

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "open": true, "tags": [] }

PUT `/v1/contact/:id`

Update contact fields: name, number, open, notes, email, locked.

Parameter	Type	Required	Description
`id`	string (path)	Yes	Contact ID (UUID), in the path.
`name`	string	No	Contact name.
`number`	string	No	New phone number for the contact.
`open`	boolean	No	Conversation state (true = open).
`notes`	string	No	Contact notes.
`email`	string	No	Contact email.
`locked`	boolean	No	Whether the contact is locked.

Example request

curl -X PUT https://api.manycontacts.com/v1/contact/8f3c... \
  -H "apikey: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Juan Pérez", "email": "juan@example.com" }'

Example response

HTTP/1.1 200 OK

Returns 200 with no body when the operation succeeds.

PUT `/v1/contact/:id/customField`

Create or update a custom field (key + value).

Parameter	Type	Required	Description
`id`	string (path)	Yes	Contact ID (UUID), in the path.
`key`	string	Yes	Custom field name.
`value`	string	Yes	Custom field value.

Example request

curl -X PUT https://api.manycontacts.com/v1/contact/8f3c.../customField \
  -H "apikey: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "dni", "value": "12345678Z" }'

Example response

HTTP/1.1 200 OK

Returns 200 with no body when the operation succeeds.

POST `/v1/contact/:id/assign/:userId`

Assign the contact to a user.

Parameter	Type	Required	Description
`id`	string (path)	Yes	Contact ID (UUID), in the path.
`userId`	string (path)	Yes	ID of the user (agent) to assign the contact to.

If the user is an AI agent and the organization has no AI credits, it returns 402 with { "error": "no_ai_credits" }.

Example request

curl -X POST https://api.manycontacts.com/v1/contact/8f3c.../assign/5d2a... \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "last_user_id": "5d2a...", "open": true, "tags": [] }

POST `/v1/contact/:id/unassign`

Remove the contact's assignment.

Parameter	Type	Required	Description
`id`	string (path)	Yes	Contact ID (UUID), in the path.

Example request

curl -X POST https://api.manycontacts.com/v1/contact/8f3c.../unassign \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "last_user_id": null, "open": true, "tags": [] }

POST `/v1/contact/:id/close`

Close the contact's conversation.

Parameter	Type	Required	Description
`id`	string (path)	Yes	Contact ID (UUID), in the path.

Example request

curl -X POST https://api.manycontacts.com/v1/contact/8f3c.../close \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "open": false, "tags": [] }

POST `/v1/contact/:id/open`

Open the contact's conversation.

Parameter	Type	Required	Description
`id`	string (path)	Yes	Contact ID (UUID), in the path.

Example request

curl -X POST https://api.manycontacts.com/v1/contact/8f3c.../open \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "open": true, "tags": [] }

POST `/v1/contact/:id/tag/:tagId`

Add a tag to the contact.

Parameter	Type	Required	Description
`id`	string (path)	Yes	Contact ID (UUID), in the path.
`tagId`	string (path)	Yes	Tag ID.

Example request

curl -X POST https://api.manycontacts.com/v1/contact/8f3c.../tag/a1b2... \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "tags": [{ "id": "a1b2...", "name": "Cliente", "color": "#55efc4" }] }

DELETE `/v1/contact/:id/tag/:tagId`

Remove a tag from the contact.

Parameter	Type	Required	Description
`id`	string (path)	Yes	Contact ID (UUID), in the path.
`tagId`	string (path)	Yes	Tag ID.

Example request

curl -X DELETE https://api.manycontacts.com/v1/contact/8f3c.../tag/a1b2... \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "tags": [] }

POST `/v1/contact/:id/team/:teamId`

Assign the contact to a team.

Parameter	Type	Required	Description
`id`	string (path)	Yes	Contact ID (UUID), in the path.
`teamId`	string (path)	Yes	Team ID.

Example request

curl -X POST https://api.manycontacts.com/v1/contact/8f3c.../team/7c9d... \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "tags": [] }

DELETE `/v1/contact/:id/team/:teamId`

Remove the contact from a team.

Parameter	Type	Required	Description
`id`	string (path)	Yes	Contact ID (UUID), in the path.
`teamId`	string (path)	Yes	Team ID.

Example request

curl -X DELETE https://api.manycontacts.com/v1/contact/8f3c.../team/7c9d... \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "tags": [] }

GET `/v1/contact/:id/mediafiles/list`

List the contact's media files (excludes audio).

Parameter	Type	Required	Description
`id`	string (path)	Yes	Contact ID (UUID), in the path.

Example request

curl https://api.manycontacts.com/v1/contact/8f3c.../mediafiles/list \
  -H "apikey: TU_API_KEY"

Example response

[
  {
    "id": "e5f6...",
    "filename": "factura.pdf",
    "mimetype": "application/pdf",
    "createdAt": "2026-07-09T13:00:00.000Z",
    "url": "https://app.manycontacts.com/api/message/8f3c.../media/e5f6..."
  }
]

GET `/v1/contact/:id/bot/init`

Trigger the chatbot's first message to the contact.

Parameter	Type	Required	Description
`id`	string (path)	Yes	Contact ID (UUID), in the path.

Example request

curl https://api.manycontacts.com/v1/contact/8f3c.../bot/init \
  -H "apikey: TU_API_KEY"

Example response

HTTP/1.1 200 OK

Returns 200 with no body when the operation succeeds.

Contacts (v2)

The v2 API identifies the contact directly by phone number in the path, instead of by ID. It includes the same assignment, tags, teams, open/close and custom-field endpoints as v1, plus these specific ones:

GET `/v2/contact/:phone`

Get the contact (includes internal notes) by phone.

Parameter	Type	Required	Description
`phone`	string (path)	Yes	Contact phone in international format (digits only), in the path.

Example request

curl https://api.manycontacts.com/v2/contact/34600111222 \
  -H "apikey: TU_API_KEY"

Example response

{
  "id": "8f3c...",
  "name": "Juan",
  "number": "34600111222",
  "open": true,
  "tags": [],
  "internal_notes": [
    { "text": "Cliente VIP", "createdAt": "2026-07-09T13:00:00.000Z" }
  ]
}

PUT `/v2/contact/:phone`

Create or update the contact by phone.

Parameter	Type	Required	Description
`phone`	string (path)	Yes	Contact phone in international format (digits only), in the path.
`name`	string	No	Contact name.
`open`	boolean	No	Conversation state (true = open).
`notes`	string	No	Contact notes.
`email`	string	No	Contact email.
`locked`	boolean	No	Whether the contact is locked.

Example request

curl -X PUT https://api.manycontacts.com/v2/contact/34600111222 \
  -H "apikey: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Juan Pérez", "email": "juan@example.com" }'

Example response

{ "id": "8f3c...", "name": "Juan Pérez", "number": "34600111222", "email": "juan@example.com", "open": true, "tags": [] }

PUT `/v2/contact/:phone/customField`

Create or update a custom field (creates the contact if it doesn't exist).

Parameter	Type	Required	Description
`phone`	string (path)	Yes	Contact phone in international format (digits only), in the path.
`key`	string	Yes	Custom field name.
`value`	string	Yes	Custom field value.

Example request

curl -X PUT https://api.manycontacts.com/v2/contact/34600111222/customField \
  -H "apikey: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "dni", "value": "12345678Z" }'

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "customFields": { "dni": "12345678Z" }, "tags": [] }

POST `/v2/contact/:phone/assign/:userId`

Assign the contact (by phone) to a user.

Parameter	Type	Required	Description
`phone`	string (path)	Yes	Contact phone in international format (digits only), in the path.
`userId`	string (path)	Yes	ID of the user (agent) to assign the contact to.

If the user is an AI agent and the organization has no AI credits, it returns 402 with { "error": "no_ai_credits" }.

Example request

curl -X POST https://api.manycontacts.com/v2/contact/34600111222/assign/5d2a... \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "last_user_id": "5d2a...", "open": true, "tags": [] }

POST `/v2/contact/:phone/unassign`

Remove the contact's assignment (by phone).

Parameter	Type	Required	Description
`phone`	string (path)	Yes	Contact phone in international format (digits only), in the path.

Example request

curl -X POST https://api.manycontacts.com/v2/contact/34600111222/unassign \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "last_user_id": null, "open": true, "tags": [] }

POST `/v2/contact/:phone/close`

Close the contact's conversation (by phone).

Parameter	Type	Required	Description
`phone`	string (path)	Yes	Contact phone in international format (digits only), in the path.

Example request

curl -X POST https://api.manycontacts.com/v2/contact/34600111222/close \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "open": false, "tags": [] }

POST `/v2/contact/:phone/open`

Open the contact's conversation (by phone).

Parameter	Type	Required	Description
`phone`	string (path)	Yes	Contact phone in international format (digits only), in the path.

Example request

curl -X POST https://api.manycontacts.com/v2/contact/34600111222/open \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "open": true, "tags": [] }

POST `/v2/contact/:phone/tag/:tagId`

Add a tag to the contact (by phone).

Parameter	Type	Required	Description
`phone`	string (path)	Yes	Contact phone in international format (digits only), in the path.
`tagId`	string (path)	Yes	Tag ID.

Example request

curl -X POST https://api.manycontacts.com/v2/contact/34600111222/tag/a1b2... \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "tags": [{ "id": "a1b2...", "name": "Cliente", "color": "#55efc4" }] }

POST `/v2/contact/:phone/tag/name/:tagName`

Add a tag by name (creates tag and contact if they don't exist).

Parameter	Type	Required	Description
`phone`	string (path)	Yes	Contact phone in international format (digits only), in the path.
`tagName`	string (path)	Yes	Tag name (created if it doesn't exist).

Example request

curl -X POST https://api.manycontacts.com/v2/contact/34600111222/tag/name/Cliente \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "tags": [{ "id": "a1b2...", "name": "Cliente", "color": "#55efc4" }] }

DELETE `/v2/contact/:phone/tag/:tagId`

Remove a tag from the contact (by phone).

Parameter	Type	Required	Description
`phone`	string (path)	Yes	Contact phone in international format (digits only), in the path.
`tagId`	string (path)	Yes	Tag ID.

Example request

curl -X DELETE https://api.manycontacts.com/v2/contact/34600111222/tag/a1b2... \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "tags": [] }

POST `/v2/contact/:phone/team/:teamId`

Assign the contact (by phone) to a team.

Parameter	Type	Required	Description
`phone`	string (path)	Yes	Contact phone in international format (digits only), in the path.
`teamId`	string (path)	Yes	Team ID.

Example request

curl -X POST https://api.manycontacts.com/v2/contact/34600111222/team/7c9d... \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "tags": [] }

DELETE `/v2/contact/:phone/team/:teamId`

Remove the contact (by phone) from a team.

Parameter	Type	Required	Description
`phone`	string (path)	Yes	Contact phone in international format (digits only), in the path.
`teamId`	string (path)	Yes	Team ID.

Example request

curl -X DELETE https://api.manycontacts.com/v2/contact/34600111222/team/7c9d... \
  -H "apikey: TU_API_KEY"

Example response

{ "id": "8f3c...", "name": "Juan", "number": "34600111222", "tags": [] }

GET `/v2/contact/:phone/mediafiles/list`

List the contact's media files (excludes audio).

Parameter	Type	Required	Description
`phone`	string (path)	Yes	Contact phone in international format (digits only), in the path.

Example request

curl https://api.manycontacts.com/v2/contact/34600111222/mediafiles/list \
  -H "apikey: TU_API_KEY"

Example response

[
  {
    "id": "e5f6...",
    "filename": "factura.pdf",
    "mimetype": "application/pdf",
    "createdAt": "2026-07-09T13:00:00.000Z",
    "url": "https://app.manycontacts.com/api/message/8f3c.../media/e5f6..."
  }
]

GET `/v2/contact/:phone/bot/init`

Trigger the chatbot's first message to the contact (by phone).

Parameter	Type	Required	Description
`phone`	string (path)	Yes	Contact phone in international format (digits only), in the path.

Example request

curl https://api.manycontacts.com/v2/contact/34600111222/bot/init \
  -H "apikey: TU_API_KEY"

Example response

HTTP/1.1 200 OK

Returns 200 with no body when the operation succeeds.

PUT `/v2/contact/:phone/stage/:column`

Move the contact to the funnel stage identified by its order.

Parameter	Type	Required	Description
`phone`	string (path)	Yes	Contact phone in international format (digits only), in the path.
`column`	integer (path)	Yes	Order (index) of the default funnel stage, starting at 0.

Example request

curl -X PUT https://api.manycontacts.com/v2/contact/34600111222/stage/2 \
  -H "apikey: TU_API_KEY"

Example response

HTTP/1.1 200 OK

Returns 200 with no body when the operation succeeds.

Parameter	Type	Required	Description
`filter`	string (query)	No	Filter tags by name (partial, case-insensitive search).

Parameter	Type	Required	Description
`name`	string	Yes	Tag name.
`color`	string	No	Color in hexadecimal format (max. 7 characters). If omitted, a random one is assigned.

Parameter	Type	Required	Description
`id`	string (path)	Yes	Tag ID.
`name`	string	No	Tag name.
`color`	string	No	Color in hexadecimal format (max. 7 characters). If omitted, a random one is assigned.

Parameter	Type	Required	Description
`id`	string (path)	Yes	Tag ID.

Teams

List your organization's teams and their members.

GET `/v1/teams`

List teams with their members.

This endpoint takes no parameters.

Example request

curl https://api.manycontacts.com/v1/teams \
  -H "apikey: TU_API_KEY"

Example response

[
  {
    "id": "7c9d...",
    "name": "Ventas",
    "members": [
      { "id": "5d2a...", "name": "Ana" },
      { "id": "6e3b...", "name": "Luis" }
    ]
  }
]

Templates (v1)

Send Meta-approved WhatsApp templates. Useful to start conversations outside the 24-hour window. v1 supports a single body variable via the text parameter.

GET `/v1/templates`

List approved and visible templates.

This endpoint takes no parameters.

Example request

curl https://api.manycontacts.com/v1/templates \
  -H "apikey: TU_API_KEY"

Example response

[
  {
    "name": "bienvenida",
    "text": "Hola {{1}}, tu cita es el {{2}}",
    "hasImage": false,
    "hasDocument": false,
    "hasVideo": false
  }
]

POST `/v1/template/:templateName/:number`

Send a template to a number (body variable in text).

Parameter	Type	Required	Description
`templateName`	string (path)	Yes	Exact name of the Meta-approved template.
`number`	string (path)	Yes	Destination phone in international format, in the path.
`text`	string	No	Value for the template body variable.

Example request

curl -X POST https://api.manycontacts.com/v1/template/bienvenida/34600111222 \
  -H "apikey: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Juan" }'

Example response

{ "id": "8f3c...", "error": null }

POST `/v1/template/:templateName/:number/media`

Send a template with a media attachment.

Parameter	Type	Required	Description
`templateName`	string (path)	Yes	Exact name of the Meta-approved template.
`number`	string (path)	Yes	Destination phone in international format, in the path.
`file`	file (multipart)	Yes	File to send (multipart/form-data).
`text`	string	No	Value for the template body variable.

Example request

curl -X POST https://api.manycontacts.com/v1/template/bienvenida/34600111222/media \
  -H "apikey: TU_API_KEY" \
  -F "text=Juan" \
  -F "file=@catalogo.pdf"

Example response

{ "id": "8f3c...", "error": null }

Templates (v2)

Enhanced template sending: accepts multiple header and body variables as arrays (header_variables and variables), with or without an attached media file.

POST `/v2/template/:templateName/:number`

Send a template with header and body variables (arrays).

Parameter	Type	Required	Description
`templateName`	string (path)	Yes	Exact name of the Meta-approved template.
`number`	string (path)	Yes	Destination phone in international format, in the path.
`header_variables`	string[]	No	Values for the template header variables (array).
`variables`	string[]	No	Values for the template body variables (array).

Example request

curl -X POST https://api.manycontacts.com/v2/template/bienvenida/34600111222 \
  -H "apikey: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "header_variables": ["ManyContacts"], "variables": ["Juan", "10:00"] }'

Example response

{ "id": "8f3c...", "error": null }

POST `/v2/template/:templateName/:number/media`

Send a v2 template with a media attachment.

Parameter	Type	Required	Description
`templateName`	string (path)	Yes	Exact name of the Meta-approved template.
`number`	string (path)	Yes	Destination phone in international format, in the path.
`file`	file (multipart)	Yes	File to send (multipart/form-data).
`header_variables`	string[]	No	Values for the template header variables (array).
`variables`	string[]	No	Values for the template body variables (array).

Example request

curl -X POST https://api.manycontacts.com/v2/template/bienvenida/34600111222/media \
  -H "apikey: TU_API_KEY" \
  -F 'variables=["Juan", "10:00"]' \
  -F "file=@catalogo.pdf"

Example response

{ "id": "8f3c...", "error": null }

Users

List the users (agents) in your organization.

GET `/v1/users`

List users with their id, name and AI flag.

This endpoint takes no parameters.

Example request

curl https://api.manycontacts.com/v1/users \
  -H "apikey: TU_API_KEY"

Example response

[
  { "id": "5d2a...", "name": "Ana", "ai": false },
  { "id": "9f8e...", "name": "Agente IA", "ai": true }
]

Webhooks

ManyContacts can forward your organization's events to your own URL via POST requests, so you can integrate events into your systems in real time.

Configure them in the app: Settings → Developers. Enable forwarding and set an HTTPS destination URL.

Each event is sent as a POST with a JSON body in this shape (event, delta and the full contact object):

{
  "event": "message_new",
  "delta": {
    "contactId": "8f3c...",
    "message": { "id": "...", "text": "Hola", "type": "received", "metadata": { "time": "2026-07-09T13:00:00.000Z" } }
  },
  "contact": {
    "id": "8f3c...",
    "name": "Juan",
    "email": null,
    "open": true,
    "last_user_id": null,
    "number": "34600111222",
    "notes": null,
    "locked": false,
    "customFields": {},
    "tags": []
  }
}

Available events

`event`	Description
`message_new`	New inbound message from the contact.
`message_sent`	Outbound message sent to the contact.
`mediafile_new`	New media file received or sent.
`contact_created`	A new contact has been created.
`contact_update`	The contact has been updated (e.g. its notes).
`contact_update_custom_fields`	The contact's custom fields have been updated.
`contact_update_tag_added`	A tag has been added to the contact.
`contact_update_tag_deleted`	A tag has been removed from the contact.
`contact_ai_welcome`	The AI agent has sent a welcome message.
`conversation_data`	Structured data extracted from the conversation by AI.
`message_flow_new`	Response received from a Meta Flow.

For safety, if your endpoint repeatedly returns errors, ManyContacts will automatically disable webhook forwarding.

Ready to integrate?

Get your API key in the app and start building. Questions? Get in touch.

Start for free Contact support

ManyContacts API

Authentication

Rate limits

Errors and status codes

Messages

POST /v1/message/text

POST /v1/message/media

POST /v1/message/note

POST /v1/message/interactive

Contacts (v1)

GET /v1/contacts

GET /v1/contact/:id

GET /v1/contact/phone/:phone

POST /v1/contact

PUT /v1/contact/:id

PUT /v1/contact/:id/customField

POST /v1/contact/:id/assign/:userId

POST /v1/contact/:id/unassign

POST /v1/contact/:id/close

POST /v1/contact/:id/open

POST /v1/contact/:id/tag/:tagId

DELETE /v1/contact/:id/tag/:tagId

POST /v1/contact/:id/team/:teamId

DELETE /v1/contact/:id/team/:teamId

GET /v1/contact/:id/mediafiles/list

GET /v1/contact/:id/bot/init

Contacts (v2)

GET /v2/contact/:phone

PUT /v2/contact/:phone

PUT /v2/contact/:phone/customField

POST /v2/contact/:phone/assign/:userId

POST /v2/contact/:phone/unassign

POST /v2/contact/:phone/close

POST /v2/contact/:phone/open

POST /v2/contact/:phone/tag/:tagId

POST /v2/contact/:phone/tag/name/:tagName

DELETE /v2/contact/:phone/tag/:tagId

POST /v2/contact/:phone/team/:teamId

DELETE /v2/contact/:phone/team/:teamId

GET /v2/contact/:phone/mediafiles/list

GET /v2/contact/:phone/bot/init

PUT /v2/contact/:phone/stage/:column

Tags

GET /v1/tags

POST /v1/tag

PUT /v1/tag/:id

DELETE /v1/tag/:id

Teams

GET /v1/teams

Templates (v1)

GET /v1/templates

POST /v1/template/:templateName/:number

POST /v1/template/:templateName/:number/media

Templates (v2)

POST /v2/template/:templateName/:number

POST /v2/template/:templateName/:number/media

Users

GET /v1/users

Webhooks

Ready to integrate?

POST `/v1/message/text`

POST `/v1/message/media`

POST `/v1/message/note`

POST `/v1/message/interactive`

GET `/v1/contacts`

GET `/v1/contact/:id`

GET `/v1/contact/phone/:phone`

POST `/v1/contact`

PUT `/v1/contact/:id`

PUT `/v1/contact/:id/customField`

POST `/v1/contact/:id/assign/:userId`

POST `/v1/contact/:id/unassign`

POST `/v1/contact/:id/close`

POST `/v1/contact/:id/open`

POST `/v1/contact/:id/tag/:tagId`

DELETE `/v1/contact/:id/tag/:tagId`

POST `/v1/contact/:id/team/:teamId`

DELETE `/v1/contact/:id/team/:teamId`

GET `/v1/contact/:id/mediafiles/list`

GET `/v1/contact/:id/bot/init`

GET `/v2/contact/:phone`

PUT `/v2/contact/:phone`

PUT `/v2/contact/:phone/customField`

POST `/v2/contact/:phone/assign/:userId`

POST `/v2/contact/:phone/unassign`

POST `/v2/contact/:phone/close`

POST `/v2/contact/:phone/open`

POST `/v2/contact/:phone/tag/:tagId`

POST `/v2/contact/:phone/tag/name/:tagName`

DELETE `/v2/contact/:phone/tag/:tagId`

POST `/v2/contact/:phone/team/:teamId`

DELETE `/v2/contact/:phone/team/:teamId`

GET `/v2/contact/:phone/mediafiles/list`

GET `/v2/contact/:phone/bot/init`

PUT `/v2/contact/:phone/stage/:column`

GET `/v1/tags`

POST `/v1/tag`

PUT `/v1/tag/:id`

DELETE `/v1/tag/:id`

GET `/v1/teams`

GET `/v1/templates`

POST `/v1/template/:templateName/:number`

POST `/v1/template/:templateName/:number/media`

POST `/v2/template/:templateName/:number`

POST `/v2/template/:templateName/:number/media`

GET `/v1/users`