Ir para o conteúdo
WhatsMarketingDeveloper Hub

Contatos

As pessoas com quem a sua organização conversa: dados, etapa do ciclo de vida, etiquetas, identidades por canal, consentimento e notas. Um contato pode ter várias identidades (seu WhatsApp, seu Instagram, seu e-mail) e todas apontam para a mesma ficha.

Listar contatos

GET/contacts

Contatos da organização, paginados e com filtros: aba (tab), etapa, proprietário (ownerId, ou none para os que não têm), origem, canal, etiqueta, busca livre (q) ou atividade recente (days). Além de data e meta, traz tabs (quantos há em cada aba) e summary (os números do cabeçalho do painel).

Permissões: contacts:read

Parâmetros

NomeOndeTipoValores
pageconsultanumberpadrão: 1 · 1 – …
pageSizeconsultanumberpadrão: 20 · 1 – 100
tabconsultastringall · leads · in_progress · customers · inactive · no_consent
lifecycleStageIdconsultauuid
ownerIdconsultastring^(none|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$
sourceconsultastringOTHER · MANUAL · IMPORT · WHATSAPP_INBOUND · CAMPAIGN · WEBSITE_FORM · REFERRAL
channelTypeconsultastringWHATSAPP · INSTAGRAM · MESSENGER · FACEBOOK · TELEGRAM · TIKTOK · WEBCHAT · EMAIL · SMS · WECHAT · VOICE
tagconsultastring0–60 caracteres
qconsultastring0–120 caracteres
searchconsultastring0–120 caracteres
daysconsultanumber7 · 30 · 90
idsconsultauuid[]≤ 500
curl
curl "https://micuenta.whatsmarketing.es/api/v1/contacts?page=1&pageSize=20" \
  -H "Authorization: Bearer $WM_API_KEY"
Node.js
const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/contacts?page=1&pageSize=20', {
  headers: {
    Authorization: `Bearer ${process.env.WM_API_KEY}`,
  },
});
const data = await res.json();
Python
import os, requests

r = requests.get(
    "https://micuenta.whatsmarketing.es/api/v1/contacts?page=1&pageSize=20",
    headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
    timeout=30,
)
r.raise_for_status()
data = r.json()
PHP
<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/contacts?page=1&pageSize=20');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WM_API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
Resposta 200
{
  "data": [
    {
      "id": "0b1c2d3e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
      "fullName": "Laura Pérez",
      "primaryPhone": "+34612345678",
      "primaryEmail": "laura@ejemplo.com",
      "company": "Clínica Sol",
      "country": "ES",
      "source": "WEBSITE_FORM",
      "lifecycleStageId": "9c2a1f00-2b3c-4d5e-8f90-1a2b3c4d5e6f",
      "lifecycleStage": {
        "id": "9c2a1f00-2b3c-4d5e-8f90-1a2b3c4d5e6f",
        "name": "Lead nuevo",
        "order": 1
      },
      "ownerId": null,
      "owner": null,
      "optedOut": false,
      "consent": {
        "given": true,
        "at": "2026-10-14T10:20:00.000Z",
        "how": "WEBSITE_FORM"
      },
      "tags": [
        "web"
      ],
      "identities": [
        {
          "id": "6d7e8f90-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
          "channelType": "WHATSAPP",
          "externalId": "34612345678"
        }
      ],
      "lastConversation": null,
      "createdAt": "2026-10-14T10:20:05.000Z",
      "updatedAt": "2026-10-14T10:20:05.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 1,
    "totalPages": 1
  },
  "tabs": {
    "all": 1,
    "leads": 1,
    "in_progress": 0,
    "customers": 0,
    "inactive": 0,
    "no_consent": 0
  },
  "summary": {
    "days": 30,
    "total": 1,
    "newInPeriod": 1,
    "withConsent": 1,
    "withoutConsent": 0,
    "consentPct": 100,
    "leadsNew": 1,
    "leadsInProgress": 0,
    "customers": 0,
    "customersNewInPeriod": 0,
    "tags": [
      "web"
    ]
  }
}

Criar um contato

POST/contacts

Cria a ficha. O telefone vai em formato internacional com prefixo (+34…). Se já existir um contato com esse telefone, responde 409 CONTACT_PHONE_EXISTS com o contactId do existente. consent registra quando e como a pessoa deu consentimento para receber mensagens; note deixa uma primeira nota interna.

Permissões: contacts:write

Corpo da requisição CreateContact

NomeTipoValores
fullNamestring0–160 caracteres
primaryPhonestring0–32 caracteres
primaryEmailemail
companystring0–160 caracteres
countrystring0–2 caracteres
sourcestringOTHER · MANUAL · IMPORT · WHATSAPP_INBOUND · CAMPAIGN · WEBSITE_FORM · REFERRAL
lifecycleStageIduuid
ownerIduuid
optedOutboolean
consentConsent
tagsstring[]≤ 50
notestring0–4000 caracteres

Erros frequentes

  • 409 CONTACT_PHONE_EXISTS Já há um contato com esse telefone; a resposta traz contactId e fullName.
curl
curl -X POST "https://micuenta.whatsmarketing.es/api/v1/contacts" \
  -H "Authorization: Bearer $WM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fullName": "Laura Pérez",
  "primaryPhone": "+34612345678",
  "primaryEmail": "laura@ejemplo.com",
  "company": "Clínica Sol",
  "country": "ES",
  "source": "WEBSITE_FORM",
  "tags": [
    "web"
  ],
  "consent": {
    "given": true,
    "at": "2026-10-14T10:20:00.000Z",
    "how": "WEBSITE_FORM"
  }
}'
Node.js
const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/contacts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WM_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "fullName": "Laura Pérez",
    "primaryPhone": "+34612345678",
    "primaryEmail": "laura@ejemplo.com",
    "company": "Clínica Sol",
    "country": "ES",
    "source": "WEBSITE_FORM",
    "tags": [
      "web"
    ],
    "consent": {
      "given": true,
      "at": "2026-10-14T10:20:00.000Z",
      "how": "WEBSITE_FORM"
    }
  }),
});
const data = await res.json();
Python
import os, requests

r = requests.post(
    "https://micuenta.whatsmarketing.es/api/v1/contacts",
    headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
    json={
        "fullName": "Laura Pérez",
        "primaryPhone": "+34612345678",
        "primaryEmail": "laura@ejemplo.com",
        "company": "Clínica Sol",
        "country": "ES",
        "source": "WEBSITE_FORM",
        "tags": [
            "web"
        ],
        "consent": {
            "given": True,
            "at": "2026-10-14T10:20:00.000Z",
            "how": "WEBSITE_FORM"
        }
    },
    timeout=30,
)
r.raise_for_status()
data = r.json()
PHP
<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/contacts');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WM_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'fullName' => 'Laura Pérez',
    'primaryPhone' => '+34612345678',
    'primaryEmail' => 'laura@ejemplo.com',
    'company' => 'Clínica Sol',
    'country' => 'ES',
    'source' => 'WEBSITE_FORM',
    'tags' => [
      'web'
    ],
    'consent' => [
      'given' => true,
      'at' => '2026-10-14T10:20:00.000Z',
      'how' => 'WEBSITE_FORM'
    ]
  ]),
]);
$data = json_decode(curl_exec($ch), true);
Resposta 201
{
  "id": "0b1c2d3e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
  "organizationId": "f0e1d2c3-b4a5-4968-8776-655443322110",
  "fullName": "Laura Pérez",
  "primaryPhone": "+34612345678",
  "primaryEmail": "laura@ejemplo.com",
  "company": "Clínica Sol",
  "country": "ES",
  "source": "WEBSITE_FORM",
  "lifecycleStageId": null,
  "lifecycleStage": null,
  "ownerId": null,
  "owner": null,
  "optedOut": false,
  "consent": {
    "given": true,
    "at": "2026-10-14T10:20:00.000Z",
    "how": "WEBSITE_FORM"
  },
  "tags": [
    "web"
  ],
  "identities": [
    {
      "id": "6d7e8f90-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
      "channelType": "WHATSAPP",
      "externalId": "34612345678"
    }
  ],
  "createdAt": "2026-10-14T10:20:05.000Z",
  "updatedAt": "2026-10-14T10:20:05.000Z"
}

Atualizar contatos em lote

POST/contacts/bulk

Até 500 contatos por chamada: mudar de etapa, adicionar etiquetas (até 20) ou reatribuir o proprietário (ownerId: null o remove). Pelo menos uma das três. skipped são os ids que não pertencem à sua organização.

Permissões: contacts:write

Corpo da requisição BulkContacts

NomeTipoValores
ids obrigatóriouuid[]≤ 500
lifecycleStageIduuid
addTagsstring[]≤ 20
ownerIduuid
curl
curl -X POST "https://micuenta.whatsmarketing.es/api/v1/contacts/bulk" \
  -H "Authorization: Bearer $WM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "0b1c2d3e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
    "4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b"
  ],
  "addTags": [
    "evento-madrid"
  ],
  "lifecycleStageId": "9c2a1f00-2b3c-4d5e-8f90-1a2b3c4d5e6f"
}'
Node.js
const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/contacts/bulk', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WM_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "ids": [
      "0b1c2d3e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
      "4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b"
    ],
    "addTags": [
      "evento-madrid"
    ],
    "lifecycleStageId": "9c2a1f00-2b3c-4d5e-8f90-1a2b3c4d5e6f"
  }),
});
const data = await res.json();
Python
import os, requests

r = requests.post(
    "https://micuenta.whatsmarketing.es/api/v1/contacts/bulk",
    headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
    json={
        "ids": [
            "0b1c2d3e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
            "4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b"
        ],
        "addTags": [
            "evento-madrid"
        ],
        "lifecycleStageId": "9c2a1f00-2b3c-4d5e-8f90-1a2b3c4d5e6f"
    },
    timeout=30,
)
r.raise_for_status()
data = r.json()
PHP
<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/contacts/bulk');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WM_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'ids' => [
      '0b1c2d3e-5f6a-4b7c-8d9e-0f1a2b3c4d5e',
      '4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b'
    ],
    'addTags' => [
      'evento-madrid'
    ],
    'lifecycleStageId' => '9c2a1f00-2b3c-4d5e-8f90-1a2b3c4d5e6f'
  ]),
]);
$data = json_decode(curl_exec($ch), true);
Resposta 201
{
  "updated": 2,
  "skipped": 0
}

Ver um contato

GET/contacts/{id}

A ficha completa: identidades por canal, consentimento, etiquetas, proprietário, etapa e oportunidades abertas.

Permissões: contacts:read

Parâmetros

NomeOndeTipoValores
id obrigatóriorotastring
curl
curl "https://micuenta.whatsmarketing.es/api/v1/contacts/{id}" \
  -H "Authorization: Bearer $WM_API_KEY"
Node.js
const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/contacts/{id}', {
  headers: {
    Authorization: `Bearer ${process.env.WM_API_KEY}`,
  },
});
const data = await res.json();
Python
import os, requests

r = requests.get(
    "https://micuenta.whatsmarketing.es/api/v1/contacts/{id}",
    headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
    timeout=30,
)
r.raise_for_status()
data = r.json()
PHP
<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/contacts/{id}');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WM_API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
Resposta 200
{
  "id": "0b1c2d3e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
  "organizationId": "f0e1d2c3-b4a5-4968-8776-655443322110",
  "fullName": "Laura Pérez",
  "primaryPhone": "+34612345678",
  "primaryEmail": "laura@ejemplo.com",
  "company": "Clínica Sol",
  "country": "ES",
  "source": "WEBSITE_FORM",
  "lifecycleStageId": null,
  "lifecycleStage": null,
  "ownerId": null,
  "owner": null,
  "optedOut": false,
  "consent": {
    "given": true,
    "at": "2026-10-14T10:20:00.000Z",
    "how": "WEBSITE_FORM"
  },
  "tags": [
    "web"
  ],
  "identities": [
    {
      "id": "6d7e8f90-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
      "channelType": "WHATSAPP",
      "externalId": "34612345678"
    }
  ],
  "createdAt": "2026-10-14T10:20:05.000Z",
  "updatedAt": "2026-10-14T10:20:05.000Z"
}

Editar um contato

PATCH/contacts/{id}

Todos os campos são opcionais; só muda o que você envia. Mudar o telefone para um que já pertence a outro contato responde 409 CONTACT_PHONE_EXISTS. Responde com a ficha atualizada.

Permissões: contacts:write

Parâmetros

NomeOndeTipoValores
id obrigatóriorotastring

Corpo da requisição UpdateContact

NomeTipoValores
fullNamestring0–160 caracteres
primaryPhonestring0–32 caracteres
primaryEmailemail
companystring0–160 caracteres
countrystring0–2 caracteres
sourcestringOTHER · MANUAL · IMPORT · WHATSAPP_INBOUND · CAMPAIGN · WEBSITE_FORM · REFERRAL
lifecycleStageIduuid
ownerIduuid
optedOutboolean
consentConsent
tagsstring[]≤ 50
curl
curl -X PATCH "https://micuenta.whatsmarketing.es/api/v1/contacts/{id}" \
  -H "Authorization: Bearer $WM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company": "Clínica Sol Fuengirola",
  "tags": [
    "web",
    "cliente"
  ],
  "lifecycleStageId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
}'
Node.js
const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/contacts/{id}', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.WM_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "company": "Clínica Sol Fuengirola",
    "tags": [
      "web",
      "cliente"
    ],
    "lifecycleStageId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  }),
});
const data = await res.json();
Python
import os, requests

r = requests.patch(
    "https://micuenta.whatsmarketing.es/api/v1/contacts/{id}",
    headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
    json={
        "company": "Clínica Sol Fuengirola",
        "tags": [
            "web",
            "cliente"
        ],
        "lifecycleStageId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
    },
    timeout=30,
)
r.raise_for_status()
data = r.json()
PHP
<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/contacts/{id}');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'PATCH',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WM_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'company' => 'Clínica Sol Fuengirola',
    'tags' => [
      'web',
      'cliente'
    ],
    'lifecycleStageId' => 'a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d'
  ]),
]);
$data = json_decode(curl_exec($ch), true);
Resposta 200
{
  "id": "0b1c2d3e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
  "organizationId": "f0e1d2c3-b4a5-4968-8776-655443322110",
  "fullName": "Laura Pérez",
  "primaryPhone": "+34612345678",
  "primaryEmail": "laura@ejemplo.com",
  "company": "Clínica Sol",
  "country": "ES",
  "source": "WEBSITE_FORM",
  "lifecycleStageId": null,
  "lifecycleStage": null,
  "ownerId": null,
  "owner": null,
  "optedOut": false,
  "consent": {
    "given": true,
    "at": "2026-10-14T10:20:00.000Z",
    "how": "WEBSITE_FORM"
  },
  "tags": [
    "web"
  ],
  "identities": [
    {
      "id": "6d7e8f90-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
      "channelType": "WHATSAPP",
      "externalId": "34612345678"
    }
  ],
  "createdAt": "2026-10-14T10:20:05.000Z",
  "updatedAt": "2026-10-14T10:20:05.000Z"
}

Excluir um contato

DELETE/contacts/{id}

Somente se o contato não tiver conversas, campanhas nem vendas; se tiver, responde 409 CONTACT_HAS_HISTORY e convém retirar o consentimento dele (optedOut: true) em vez de excluí-lo. As notas e identidades são excluídas junto com ele.

Permissões: contacts:write

Parâmetros

NomeOndeTipoValores
id obrigatóriorotastring

Erros frequentes

  • 409 CONTACT_HAS_HISTORY O contato tem histórico: não é excluído para que os relatórios continuem batendo.
curl
curl -X DELETE "https://micuenta.whatsmarketing.es/api/v1/contacts/{id}" \
  -H "Authorization: Bearer $WM_API_KEY"
Node.js
const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/contacts/{id}', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.WM_API_KEY}`,
  },
});
const data = await res.json();
Python
import os, requests

r = requests.delete(
    "https://micuenta.whatsmarketing.es/api/v1/contacts/{id}",
    headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
    timeout=30,
)
r.raise_for_status()
data = r.json()
PHP
<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/contacts/{id}');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'DELETE',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WM_API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
Resposta 200
{
  "deleted": true
}

Linha do tempo de um contato

GET/contacts/{id}/timeline

Conversas, campanhas recebidas, notas, mudanças de etapa, consentimento e cadastro, em ordem cronológica inversa. type filtra por conversations, campaigns ou notes; cada entrada leva o seu type.

Permissões: contacts:read

Parâmetros

NomeOndeTipoValores
id obrigatóriorotastring
pageconsultanumberpadrão: 1 · 1 – …
pageSizeconsultanumberpadrão: 20 · 1 – 100
typeconsultastringall · conversations · campaigns · notes
curl
curl "https://micuenta.whatsmarketing.es/api/v1/contacts/{id}/timeline?page=1&pageSize=20" \
  -H "Authorization: Bearer $WM_API_KEY"
Node.js
const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/contacts/{id}/timeline?page=1&pageSize=20', {
  headers: {
    Authorization: `Bearer ${process.env.WM_API_KEY}`,
  },
});
const data = await res.json();
Python
import os, requests

r = requests.get(
    "https://micuenta.whatsmarketing.es/api/v1/contacts/{id}/timeline?page=1&pageSize=20",
    headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
    timeout=30,
)
r.raise_for_status()
data = r.json()
PHP
<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/contacts/{id}/timeline?page=1&pageSize=20');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WM_API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
Resposta 200
{
  "data": [
    {
      "id": "7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
      "type": "campaign",
      "at": "2026-10-10T08:00:00.000Z",
      "campaign": {
        "id": "3a4b5c6d-7e8f-4a9b-8c0d-1e2f3a4b5c6d",
        "name": "Octubre: promo"
      },
      "status": "DELIVERED",
      "sentAt": "2026-10-10T08:00:02.000Z",
      "deliveredAt": "2026-10-10T08:00:05.000Z",
      "readAt": null,
      "failedAt": null,
      "errorMessage": null
    },
    {
      "id": "8d9e0f1a-2b3c-4d4e-9f5a-6b7c8d9e0f1a",
      "type": "note",
      "at": "2026-10-09T17:12:00.000Z",
      "author": "Ana Gómez",
      "body": "Pidió presupuesto por teléfono"
    },
    {
      "id": "9e0f1a2b-3c4d-4e5f-8a6b-7c8d9e0f1a2b",
      "type": "stage",
      "at": "2026-10-09T17:00:00.000Z",
      "by": "Ana Gómez",
      "from": "Lead nuevo",
      "to": "En proceso",
      "bulk": false
    },
    {
      "id": "0b1c2d3e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
      "type": "created",
      "at": "2026-10-01T09:00:00.000Z",
      "source": "WEBSITE_FORM"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 4,
    "totalPages": 1
  }
}

Adicionar uma identidade de canal

POST/contacts/{id}/identities

Vincula outro canal à mesma ficha: channelType é o tipo de canal (WHATSAPP, INSTAGRAM, MESSENGER, EMAIL…) e externalId o identificador do contato nesse canal (telefone sem + para WhatsApp, usuário para Instagram, e-mail para email). Se essa identidade já pertencer a outro contato, responde 409.

Permissões: contacts:write

Parâmetros

NomeOndeTipoValores
id obrigatóriorotastring

Corpo da requisição AddIdentity

NomeTipoValores
channelType obrigatóriostringWHATSAPP · INSTAGRAM · MESSENGER · FACEBOOK · TELEGRAM · TIKTOK · WEBCHAT · EMAIL · SMS · WECHAT · VOICE
externalId obrigatóriostring
curl
curl -X POST "https://micuenta.whatsmarketing.es/api/v1/contacts/{id}/identities" \
  -H "Authorization: Bearer $WM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "channelType": "INSTAGRAM",
  "externalId": "laura.perez"
}'
Node.js
const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/contacts/{id}/identities', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WM_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "channelType": "INSTAGRAM",
    "externalId": "laura.perez"
  }),
});
const data = await res.json();
Python
import os, requests

r = requests.post(
    "https://micuenta.whatsmarketing.es/api/v1/contacts/{id}/identities",
    headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
    json={
        "channelType": "INSTAGRAM",
        "externalId": "laura.perez"
    },
    timeout=30,
)
r.raise_for_status()
data = r.json()
PHP
<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/contacts/{id}/identities');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WM_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'channelType' => 'INSTAGRAM',
    'externalId' => 'laura.perez'
  ]),
]);
$data = json_decode(curl_exec($ch), true);
Resposta 201
{
  "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "contactId": "0b1c2d3e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
  "channelId": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c",
  "channel": {
    "id": "5f6a7b8c-9d0e-4f1a-8b2c-3d4e5f6a7b8c",
    "type": "INSTAGRAM"
  },
  "externalId": "laura.perez"
}

Listar notas de um contato

GET/contacts/{id}/notes

Notas internas da equipe, da mais recente à mais antiga, com autor e data.

Permissões: contacts:read

Parâmetros

NomeOndeTipoValores
id obrigatóriorotastring
pageconsultanumberpadrão: 1 · 1 – …
pageSizeconsultanumberpadrão: 20 · 1 – 100
curl
curl "https://micuenta.whatsmarketing.es/api/v1/contacts/{id}/notes?page=1&pageSize=20" \
  -H "Authorization: Bearer $WM_API_KEY"
Node.js
const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/contacts/{id}/notes?page=1&pageSize=20', {
  headers: {
    Authorization: `Bearer ${process.env.WM_API_KEY}`,
  },
});
const data = await res.json();
Python
import os, requests

r = requests.get(
    "https://micuenta.whatsmarketing.es/api/v1/contacts/{id}/notes?page=1&pageSize=20",
    headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
    timeout=30,
)
r.raise_for_status()
data = r.json()
PHP
<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/contacts/{id}/notes?page=1&pageSize=20');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WM_API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
Resposta 200
{
  "data": [
    {
      "id": "8d9e0f1a-2b3c-4d4e-9f5a-6b7c8d9e0f1a",
      "contactId": "0b1c2d3e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
      "authorId": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
      "author": {
        "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
        "fullName": "Ana Gómez"
      },
      "body": "Pidió presupuesto por teléfono",
      "createdAt": "2026-10-09T17:12:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 1,
    "totalPages": 1
  }
}

Adicionar uma nota

POST/contacts/{id}/notes

A nota fica em nome do usuário que criou a chave de API.

Permissões: contacts:write

Parâmetros

NomeOndeTipoValores
id obrigatóriorotastring

Corpo da requisição CreateContactNote

NomeTipoValores
body obrigatóriostring1–… caracteres
curl
curl -X POST "https://micuenta.whatsmarketing.es/api/v1/contacts/{id}/notes" \
  -H "Authorization: Bearer $WM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "Llamada hecha: le interesa el plan Pyme."
}'
Node.js
const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/contacts/{id}/notes', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WM_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "body": "Llamada hecha: le interesa el plan Pyme."
  }),
});
const data = await res.json();
Python
import os, requests

r = requests.post(
    "https://micuenta.whatsmarketing.es/api/v1/contacts/{id}/notes",
    headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
    json={
        "body": "Llamada hecha: le interesa el plan Pyme."
    },
    timeout=30,
)
r.raise_for_status()
data = r.json()
PHP
<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/contacts/{id}/notes');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WM_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'body' => 'Llamada hecha: le interesa el plan Pyme.'
  ]),
]);
$data = json_decode(curl_exec($ch), true);
Resposta 201
{
  "id": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
  "contactId": "0b1c2d3e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
  "authorId": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
  "author": {
    "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "fullName": "Ana Gómez"
  },
  "body": "Llamada hecha: le interesa el plan Pyme.",
  "createdAt": "2026-10-14T11:00:00.000Z"
}

Esquemas

Consent

NomeTipoValores
given obrigatórioboolean
atstring
howstringOTHER · WEBSITE_FORM · PHONE · WHATSAPP_REPLY · CONTRACT