Contatos

Com a API de contatos você pode gerenciar os contatos da sua empresa, incluindo campos personalizados e notas.

Listar Campos Personalizados

GET https://api.tinko.com.br/v1/contacts/customfields

Retorna todos os campos personalizados disponíveis para cadastro de contatos.

Headers

Nome	Tipo	Obrigatório	Descrição
Authorization	string	Sim	Token de autenticação. Ex: Bearer seu_token

Query Parameters

Nome	Tipo	Obrigatório	Descrição
page	integer	Não	Número da página. Default: 1
per_page	integer	Não	Registros por página (máx: 100). Default: 20
name	string	Não	Filtrar por nome do campo (busca parcial). Default: todos
type	string	Não	Filtrar por tipo: text, number, email, date, select. Default: todos
is_active	boolean	Não	Filtrar por status ativo/inativo. Default: todos

Exemplo de requisição

curl -X GET "https://api.tinko.com.br/v1/contacts/customfields?is_active=true" \
  -H "Authorization: Bearer SEU_TOKEN"

Response

{
  "success": true,
  "data": [
    {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "name": "cpf",
      "type": "text",
      "placeholder": "Digite o CPF",
      "options": null,
      "is_active": true,
      "order": 1
    },
    {
      "id": "01hxyz123abc456def789ghjkm",
      "name": "data_nascimento",
      "type": "date",
      "placeholder": "Data de nascimento",
      "options": null,
      "is_active": true,
      "order": 2
    },
    {
      "id": "01j7m8n9p0q1r2s3t4u5v6w7x",
      "name": "plano",
      "type": "select",
      "placeholder": "Selecione o plano",
      "options": ["Básico", "Intermediário", "Premium"],
      "is_active": true,
      "order": 3
    }
  ],
  "pagination": {
    "total": 3,
    "per_page": 20,
    "current_page": 1,
    "last_page": 1
  }
}

Campos do Response

Campo	Tipo	Descrição
id	string	ID do campo
name	string	Nome/identificador do campo
type	string	Tipo: text, number, email, date, select
placeholder	string	Texto de placeholder do campo
options	array/null	Opções disponíveis (apenas para tipo select)
is_active	boolean	Se o campo está ativo
order	integer	Ordem de exibição

Listar Contatos

GET https://api.tinko.com.br/v1/contacts

Retorna todos os contatos da empresa autenticada.

Headers

Nome	Tipo	Obrigatório	Descrição
Authorization	string	Sim	Token de autenticação. Ex: Bearer seu_token

Query Parameters

Nome	Tipo	Obrigatório	Descrição
page	integer	Não	Número da página. Default: 1
per_page	integer	Não	Registros por página (máx: 100). Default: 20
name	string	Não	Filtrar por nome (busca parcial). Default: todos
phone	string	Não	Filtrar por telefone (busca parcial). Default: todos
tag	string	Não	Filtrar por ID da tag. Default: todos
blocked	boolean	Não	Filtrar por status de bloqueio. Default: todos

Exemplo de requisição

curl -X GET "https://api.tinko.com.br/v1/contacts?name=João&blocked=false" \
  -H "Authorization: Bearer SEU_TOKEN"

Response

{
  "success": true,
  "data": [
    {
      "id": "01hxyz123abc456def789ghjkm",
      "phone": "5511999999999",
      "name": "João Silva",
      "avatar": "https://exemplo.com/avatar.jpg",
      "type": "whatsapp",
      "blocked": false,
      "customfields": {
        "cpf": "123.456.789-00",
        "plano": "Premium"
      },
      "tags": [
        {
          "id": "01j7m8n9p0q1r2s3t4u5v6w7x",
          "name": "Cliente VIP"
        }
      ],
      "created_at": "2025-10-29T10:30:00.000000Z",
      "updated_at": "2025-10-29T10:30:00.000000Z"
    }
  ],
  "pagination": {
    "total": 150,
    "per_page": 20,
    "current_page": 1,
    "last_page": 8
  }
}

Campos do Response

Campo	Tipo	Descrição
id	string	ID do contato
phone	string	Número de telefone com código do país
name	string	Nome do contato
avatar	string/null	URL da foto do contato
type	string	Tipo do contato
blocked	boolean	Se o contato está bloqueado
customfields	object	Campos personalizados preenchidos
tags	array	Tags vinculadas ao contato
created_at	string	Data de criação
updated_at	string	Data da última atualização

Visualizar Contato

GET https://api.tinko.com.br/v1/contacts/{id}

Retorna os detalhes de um contato específico.

Headers

Nome	Tipo	Obrigatório	Descrição
Authorization	string	Sim	Token de autenticação. Ex: Bearer seu_token

Path Parameters

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	ID do contato

Exemplo de requisição

curl -X GET "https://api.tinko.com.br/v1/contacts/01hxyz123abc456def789ghjkm" \
  -H "Authorization: Bearer SEU_TOKEN"

Response

{
  "success": true,
  "data": {
    "id": "01hxyz123abc456def789ghjkm",
    "phone": "5511999999999",
    "name": "João Silva",
    "avatar": "https://exemplo.com/avatar.jpg",
    "type": "whatsapp",
    "blocked": false,
    "customfields": {
      "cpf": "123.456.789-00",
      "plano": "Premium"
    },
    "tags": [
      {
        "id": "01j7m8n9p0q1r2s3t4u5v6w7x",
        "name": "Cliente VIP"
      }
    ],
    "created_at": "2025-10-29T10:30:00.000000Z",
    "updated_at": "2025-10-29T10:30:00.000000Z"
  }
}

Criar Contato

POST https://api.tinko.com.br/v1/contacts

Cria um novo contato.

Campo	Tipo	Obrigatório	Descrição
phone	string	Sim	Número de telefone com código do país
name	string	Não	Nome do contato
blocked	boolean	Não	Se o contato está bloqueado. Default: false
customfields	object	Não	Campos personalizados
tags	array	Não	Array com IDs das tags a vincular

Para obter os IDs das tags disponíveis, veja: Listar Tags.

Para obter os campos personalizados disponíveis, veja: Listar Campos Personalizados.

Exemplo de requisição

curl -X POST "https://api.tinko.com.br/v1/contacts" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "name": "João Silva",
    "blocked": false,
    "customfields": {
      "cpf": "123.456.789-00",
      "plano": "Premium"
    },
    "tags": ["01j7m8n9p0q1r2s3t4u5v6w7x", "01k8l9m0n1o2p3q4r5s6t7u8v9w"]
  }'

Response

{
  "success": true,
  "message": "Contato criado com sucesso.",
  "data": {
    "id": "01hxyz123abc456def789ghjkm",
    "phone": "5511999999999",
    "name": "João Silva",
    "avatar": null,
    "type": "whatsapp",
    "blocked": false,
    "customfields": {
      "cpf": "123.456.789-00",
      "plano": "Premium"
    },
    "tags": [
      {
        "id": "01j7m8n9p0q1r2s3t4u5v6w7x",
        "name": "Cliente VIP"
      },
      {
        "id": "01k8l9m0n1o2p3q4r5s6t7u8v9w",
        "name": "Novo"
      }
    ],
    "created_at": "2025-10-29T10:30:00.000000Z",
    "updated_at": "2025-10-29T10:30:00.000000Z"
  }
}

Erros

{
  "success": false,
  "message": "Erro de validação",
  "errors": [
    {
      "code": "FIELD_REQUIRED",
      "field": "phone",
      "message": "O campo phone é obrigatório."
    }
  ]
}

{
  "success": false,
  "message": "Erro de validação",
  "errors": [
    {
      "code": "DUPLICATE_ENTRY",
      "field": "phone",
      "message": "Já existe um contato com este telefone."
    }
  ]
}

Atualizar Contato

PUT https://api.tinko.com.br/v1/contacts/{id}

Atualiza os dados de um contato existente.

Path Parameters

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	ID do contato

Request Body

Campo	Tipo	Obrigatório	Descrição
name	string	Não	Nome do contato
blocked	boolean	Não	Se o contato está bloqueado
customfields	object	Não	Campos personalizados
tags	array	Não	Array com IDs das tags (substitui as existentes)

Para obter os IDs das tags disponíveis, veja: Listar Tags.

Para obter os campos personalizados disponíveis, veja: Listar Campos Personalizados.

Nota

O número de telefone não pode ser alterado após a criação do contato.

Exemplo de requisição

curl -X PUT "https://api.tinko.com.br/v1/contacts/01hxyz123abc456def789ghjkm" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João Silva",
    "customfields": {
      "cpf": "123.456.789-00",
      "plano": "Básico"
    },
    "tags": ["01k8l9m0n1o2p3q4r5s6t7u8v9w"]
  }'

Response

{
  "success": true,
  "message": "Contato atualizado com sucesso.",
  "data": {
    "id": "01hxyz123abc456def789ghjkm",
    "phone": "5511999999999",
    "name": "João Silva",
    "avatar": "https://exemplo.com/avatar.jpg",
    "type": "whatsapp",
    "blocked": false,
    "customfields": {
      "cpf": "123.456.789-00",
      "plano": "Básico"
    },
    "tags": [
      {
        "id": "01k8l9m0n1o2p3q4r5s6t7u8v9w",
        "name": "Suporte"
      }
    ],
    "created_at": "2025-10-29T10:30:00.000000Z",
    "updated_at": "2025-10-30T14:20:00.000000Z"
  }
}

Erros

{
  "success": false,
  "message": "Contato não encontrado."
}

Excluir Contato

DELETE https://api.tinko.com.br/v1/contacts/{id}

Remove um contato e todos os chats vinculados a ele.

Atenção

Ao excluir um contato, todos os chats e mensagens associados serão excluídos permanentemente.

Path Parameters

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	ID do contato

Exemplo de requisição

curl -X DELETE "https://api.tinko.com.br/v1/contacts/01hxyz123abc456def789ghjkm" \
  -H "Authorization: Bearer SEU_TOKEN"

Response

{
  "success": true,
  "message": "Contato excluído com sucesso."
}

Erros

{
  "success": false,
  "message": "Contato não encontrado."
}

Listar Notas do Contato

GET https://api.tinko.com.br/v1/contacts/{id}/notes

Retorna todas as notas de um contato específico.

Headers

Nome	Tipo	Obrigatório	Descrição
Authorization	string	Sim	Token de autenticação. Ex: Bearer seu_token

Path Parameters

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	ID do contato

Query Parameters

Nome	Tipo	Obrigatório	Descrição
page	integer	Não	Número da página. Default: 1
per_page	integer	Não	Registros por página (máx: 100). Default: 20

Exemplo de requisição

curl -X GET "https://api.tinko.com.br/v1/contacts/01hxyz123abc456def789ghjkm/notes" \
  -H "Authorization: Bearer SEU_TOKEN"

Response

{
  "success": true,
  "data": [
    {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "content": "Cliente solicitou contato para renovação do plano.",
      "user": {
        "id": "01hxyz123abc456def789ghjkm",
        "name": "João Silva"
      },
      "created_at": "2025-10-29T10:30:00.000000Z"
    },
    {
      "id": "01j7m8n9p0q1r2s3t4u5v6w7x",
      "content": "Enviado proposta por e-mail.",
      "user": {
        "id": "01hxyz123abc456def789ghjkm",
        "name": "João Silva"
      },
      "created_at": "2025-10-28T15:45:00.000000Z"
    }
  ],
  "pagination": {
    "total": 2,
    "per_page": 20,
    "current_page": 1,
    "last_page": 1
  }
}

Campos do Response

Campo	Tipo	Descrição
id	string	ID da nota
content	string	Conteúdo da nota
user	object	Usuário que criou a nota
created_at	string	Data de criação

Criar Nota no Contato

POST https://api.tinko.com.br/v1/contacts/{id}/notes

Adiciona uma nota a um contato.

Path Parameters

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	ID do contato

Request Body

Campo	Tipo	Obrigatório	Descrição
content	string	Sim	Conteúdo da nota

Exemplo de requisição

curl -X POST "https://api.tinko.com.br/v1/contacts/01hxyz123abc456def789ghjkm/notes" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Cliente solicitou contato para renovação do plano."
  }'

Response

{
  "success": true,
  "message": "Nota criada com sucesso.",
  "data": {
    "id": "01arz3ndektsv4rrffq69g5fav",
    "content": "Cliente solicitou contato para renovação do plano.",
    "user": {
      "id": "01hxyz123abc456def789ghjkm",
      "name": "João Silva"
    },
    "created_at": "2025-10-29T10:30:00.000000Z"
  }
}

Erros

{
  "success": false,
  "message": "Contato não encontrado."
}

{
  "success": false,
  "message": "Erro de validação",
  "errors": [
    {
      "code": "FIELD_REQUIRED",
      "field": "content",
      "message": "O campo content é obrigatório."
    }
  ]
}

Verificar Número

POST https://api.tinko.com.br/v1/contacts/verifynumber

Tipo de canal

Para usar este endpoint, o canal deve ser um WhatsApp conectado via API (tipo whatsapp_unofficial).

Verifica se um número de telefone existe no WhatsApp e se pode receber mensagem no canal informado.

Campo	Tipo	Obrigatório	Descrição
phone	string	Sim	Número com código do país. Ex: 5511999999999
channel	string	Sim	Token do canal WhatsApp que fará a verificação

Exemplo de requisição

curl -X POST "https://api.tinko.com.br/v1/contacts/verifynumber" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "channel": "01arz3ndektsv4rrffq69g5fav"
  }'

Response

A requisição é considerada processada quando o canal está disponível para realizar a checagem. Nesse caso, o retorno é success: true e o resultado vem em data.valid.

Número válido

{
  "success": true,
  "data": {
    "valid": true,
    "phone": "5511999999999",
    "can_receive_message": true,
    "is_business": false
  }
}

Número inválido

{
  "success": true,
  "data": {
    "valid": false,
    "phone": "5511999999999",
    "can_receive_message": false,
    "reason": "NUMBER_NOT_ON_WHATSAPP"
  }
}

Erros

Canal desconectado

Status: 409

{
  "success": false,
  "message": "Canal WhatsApp desconectado.",
  "errors": [
    {
      "code": "CHANNEL_DISCONNECTED",
      "message": "O canal está desconectado. Reconecte o canal para realizar a verificação."
    }
  ]
}

Validação

Status: 422

{
  "success": false,
  "message": "Erro de validação",
  "errors": [
    {
      "code": "FIELD_REQUIRED",
      "field": "phone",
      "message": "O campo phone é obrigatório."
    }
  ]
}

Campos do Response

Campo	Tipo	Descrição
valid	boolean	Se o número existe no WhatsApp
phone	string	Número consultado
can_receive_message	boolean	Se pode receber mensagens
is_business	boolean	Se é conta Business
reason	string	Motivo quando valid é false