Contatos

Cadastre e encontre seus clientes, ligue-os aos canais de atendimento e aja em lote a partir do seu sistema (API v1).

API v1. Todos os endpoints desta página ficam em https://api.atys.pro/api/v1/contacts/, respondem JSON e têm contrato estável: mudanças incompatíveis só entram numa versão nova.

Como funciona

Tudo o que a equipe faz na tela de Contatos da Atys também pode ser feito pela API: cadastrar e encontrar clientes, ligá-los aos canais de atendimento (WhatsApp, Instagram, e-mail…), preencher campos personalizados, etiquetar e agir em lote. O contato é a base dos outros módulos: o id dele é o que o CRM (contact_ids) e a Agenda (contact_id) pedem.

Dois conceitos:

  • Contato — a pessoa ou empresa: nome, e-mail, telefone, campos personalizados.
  • Canal do contato — o contato num canal de atendimento da sua empresa (por exemplo, o WhatsApp da loja). É nele que ficam atendente, setor, etiquetas de atendimento e a conversa.

Autenticação e permissões

Use uma chave de API com as permissões de Contatos que a integração precisa:

Permissão da chaveLibera
Consultar contatosTodos os GET: contatos, canais, campos, etiquetas, status de importação e exportação.
Gerenciar contatosCriar e editar contatos e canais, campos e etiquetas; ações em lote, importação e exportação.
Excluir contatosExclusão individual e em lote. Separada de propósito: só dê se a integração realmente exclui.

A chave enxerga os mesmos contatos e canais que o usuário API enxerga na plataforma (setores e canais atribuídos a ele) e só faz o que as permissões dele permitem.

Campos personalizados (catálogo)

Os campos personalizados do contato cadastrados em Configurações, com a categoria, na ordem da tela. Use o id como field_id ao gravar valores. O type define o formato aceito: text, textarea, number, price (centavos), percentage, date, email, url, phone, cpf_cnpj, cep, checkbox (true/false), select e checkbox_group (uma das options).

GET https://api.atys.pro/api/v1/contacts/custom-fields Listar campos personalizados

Exemplos de código — listar campos personalizados

cURL
curl "https://api.atys.pro/api/v1/contacts/custom-fields" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": [
    {
      "id": 55,
      "name": "CPF",
      "type": "cpf_cnpj",
      "type_label": "CPF/CNPJ",
      "description": null,
      "options": null,
      "category": {
        "id": 3,
        "name": "Informações adicionais"
      },
      "position": 1
    },
    {
      "id": 57,
      "name": "Interesse",
      "type": "select",
      "type_label": "Lista",
      "description": null,
      "options": [
        "Compra",
        "Aluguel"
      ],
      "category": {
        "id": 3,
        "name": "Informações adicionais"
      },
      "position": 2
    }
  ]
}

Etiquetas de contato (catálogo)

Etiquetas de atendimento que a chave pode usar — a mesma regra da tela (etiquetas restritas a setor, canal ou colaborador só aparecem para quem tem acesso).

GET https://api.atys.pro/api/v1/contacts/tags Listar etiquetas de contato

Exemplos de código — listar etiquetas de contato

cURL
curl "https://api.atys.pro/api/v1/contacts/tags" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": [
    {
      "id": 9,
      "name": "VIP",
      "description": null,
      "color": "#f59e0b"
    }
  ]
}

Canais da empresa

Os canais de atendimento (números de WhatsApp, Instagram, Telegram…) que o usuário API atende. É o company_channel_id que os endpoints de criação pedem: canal fora desta lista responde 422 invalid_company_channel.

GET https://api.atys.pro/api/v1/contacts/company-channels Listar canais da empresa

Exemplos de código — listar canais da empresa

cURL
curl "https://api.atys.pro/api/v1/contacts/company-channels" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": [
    {
      "id": 44,
      "name": "WhatsApp da Loja",
      "channel_type": {
        "id": 3,
        "name": "CHANNEL_TYPE_OFC_WHATSAPP",
        "description": "Whatsapp oficial"
      }
    },
    {
      "id": 45,
      "name": "Comercial",
      "channel_type": {
        "id": 2,
        "name": "CHANNEL_TYPE_WHATSAPP",
        "description": "Whatsapp"
      }
    }
  ]
}

Origens, setores e atendentes

Origens possíveis de um canal do contato (filtro origin_id da listagem), setores da empresa e usuários ativos que podem ser atendentes (sector_id e user_id dos canais). Contatos e canais criados pela API ficam com a origem CONTACT_ORIGIN_API.

GET https://api.atys.pro/api/v1/contacts/origins Listar origens

Exemplos de código — listar origens

cURL
curl "https://api.atys.pro/api/v1/contacts/origins" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": [
    {
      "id": 2,
      "name": "CONTACT_ORIGIN_MANUAL",
      "description": "Manual"
    },
    {
      "id": 4,
      "name": "CONTACT_ORIGIN_API",
      "description": "API"
    }
  ]
}
GET https://api.atys.pro/api/v1/contacts/sectors Listar setores

Exemplos de código — listar setores

cURL
curl "https://api.atys.pro/api/v1/contacts/sectors" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": [
    {
      "id": 6,
      "name": "Comercial",
      "description": null
    }
  ]
}
GET https://api.atys.pro/api/v1/contacts/users Listar atendentes

Exemplos de código — listar atendentes

cURL
curl "https://api.atys.pro/api/v1/contacts/users" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": [
    {
      "id": 81,
      "name": "Ana Atendente",
      "email": "ana@loja.com.br"
    }
  ]
}

Criar contato

Faz o mesmo que o botão Novo contato da tela: cria o contato e, para cada item de channels, o canal do contato naquele canal da empresa. O identificador é normalizado como na plataforma — no WhatsApp o número é gravado só com dígitos, com DDI e DDD. Sem channels, cria só o contato (útil para vincular a um negócio do CRM ou a um evento da Agenda).

CampoTipoObrigatórioDescrição
namestring (255)SimNome do contato.
emailstring (100)NãoE-mail; único por empresa.
descriptionstringNãoObservações sobre o contato.
channelsarray (até 20)NãoCanais do contato. Cada item: company_channel_id e key (obrigatórios), name, user_id e sector_id (opcionais).
channels[].company_channel_idintegerSimUm dos canais da empresa.
channels[].keystring (50)SimIdentificador no canal: telefone com DDI e DDD no WhatsApp, @usuario no Instagram, id ou @usuario no Telegram.
channels[].namestringNãoNome do contato naquele canal; default o name.
channels[].user_id / sector_idintegerNãoAtendente e setor iniciais (catálogos).
tag_idsinteger[]NãoEtiquetas aplicadas a cada canal criado (etiquetas). Exige channels.
custom_fieldsarrayNão[{"field_id": 55, "value": "529.982.247-25"}]. Com canais, os valores vão para o primeiro canal criado (como na tela); sem canais, para o contato.
POST https://api.atys.pro/api/v1/contacts Criar contato

Exemplos de código — criar contato

cURL
curl -X POST "https://api.atys.pro/api/v1/contacts" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Cliente",
    "email": "maria@cliente.com.br",
    "channels": [
      {
        "company_channel_id": 44,
        "key": "+55 (11) 98888-7777"
      }
    ],
    "tag_ids": [9],
    "custom_fields": [
      {
        "field_id": 55,
        "value": "529.982.247-25"
      }
    ]
  }'
201 Created
{
  "data": {
    "id": 5120,
    "name": "Maria Cliente",
    "email": "maria@cliente.com.br",
    "description": null,
    "kind": "person",
    "organization_id": null,
    "is_group": false,
    "channels": [
      {
        "id": 77120,
        "contact_id": 5120,
        "name": "Maria Cliente",
        "key": "5511988887777",
        "is_group": false,
        "channel_type": {
          "id": 3,
          "name": "CHANNEL_TYPE_OFC_WHATSAPP",
          "description": "Whatsapp oficial"
        },
        "company_channel": {
          "id": 44,
          "name": "WhatsApp da Loja"
        },
        "origin": {
          "id": 4,
          "name": "CONTACT_ORIGIN_API"
        },
        "sector": null,
        "assigned_user": null,
        "status_id": null,
        "tags": [
          {
            "id": 9,
            "name": "VIP",
            "color": "#f59e0b"
          }
        ],
        "last_message_at": "2026-11-04T15:20:00-03:00",
        "created_at": "2026-11-04T15:20:00-03:00",
        "updated_at": "2026-11-04T15:20:00-03:00"
      }
    ],
    "created_at": "2026-11-04T15:20:00-03:00",
    "updated_at": "2026-11-04T15:20:00-03:00"
  },
  "meta": {
    "contact_was_existing": false,
    "skipped_channels": []
  }
}

Erros específicos (422): invalid_company_channel, invalid_user, invalid_sector, invalid_tag, tags_require_channel, unknown_custom_field (com field_ids) e invalid_custom_field_value (valor fora do formato do tipo, com field_id). Número de WhatsApp que não existe também responde 422. Nada é gravado quando há erro de validação.

Contato que já existe

A criação não duplica pessoas, com a mesma regra da tela: se algum identificador de channels já pertence a um contato da empresa, ou se o email já está cadastrado, o contato existente é reaproveitado (os dados dele não são sobrescritos) e só os canais novos são criados. Canal que já existe naquele canal da empresa é pulado e aparece em meta.skipped_channels com o existing_channel_id. Nesse caso a resposta é 200 OK com meta.contact_was_existing = true — por isso é seguro repetir a chamada. Campos personalizados só são gravados quando algum canal (ou o contato) é criado; para atualizar um contato existente use campos do canal ou do contato.

POST https://api.atys.pro/api/v1/contacts Criar contato que já existe

Exemplos de código — criar contato que já existe

cURL
curl -X POST "https://api.atys.pro/api/v1/contacts" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria",
    "channels": [
      {
        "company_channel_id": 44,
        "key": "5511988887777"
      }
    ]
  }'
200 OK
{
  "data": {
    "id": 5120,
    "name": "Maria Cliente",
    "email": "maria@cliente.com.br",
    "description": null,
    "kind": "person",
    "organization_id": null,
    "is_group": false,
    "channels": [
      {
        "id": 77120,
        "contact_id": 5120,
        "name": "Maria Cliente",
        "key": "5511988887777",
        "is_group": false,
        "channel_type": {
          "id": 3,
          "name": "CHANNEL_TYPE_OFC_WHATSAPP",
          "description": "Whatsapp oficial"
        },
        "company_channel": {
          "id": 44,
          "name": "WhatsApp da Loja"
        },
        "origin": {
          "id": 4,
          "name": "CONTACT_ORIGIN_API"
        },
        "sector": null,
        "assigned_user": null,
        "status_id": null,
        "tags": [
          {
            "id": 9,
            "name": "VIP",
            "color": "#f59e0b"
          }
        ],
        "last_message_at": "2026-11-04T15:20:00-03:00",
        "created_at": "2026-11-04T15:20:00-03:00",
        "updated_at": "2026-11-04T15:20:00-03:00"
      }
    ],
    "created_at": "2026-11-04T15:20:00-03:00",
    "updated_at": "2026-11-04T15:20:00-03:00"
  },
  "meta": {
    "contact_was_existing": true,
    "skipped_channels": [
      {
        "key": "5511988887777",
        "channel_type_id": 3,
        "reason": "already_exists",
        "existing_channel_id": 77120
      }
    ]
  }
}

Listar e buscar contatos

Os contatos que a chave enxerga, do mais recentemente alterado para o mais antigo. Vale a mesma visibilidade das conversas na plataforma: um contato aparece quando algum canal dele está num setor, atendente e canal da empresa ao alcance do usuário API — ou quando ainda não tem canal nenhum. Em cada contato, channels traz só os canais visíveis.

ParâmetroTipoDescrição
qstringBusca por nome ou e-mail (palavra a palavra, sem diferenciar acento) e por telefone/identificador do canal — com e sem o 9º dígito.
tag_ids[]integer[]Contatos com algum canal que tenha uma destas etiquetas.
company_channel_idintegerContatos com canal neste canal da empresa.
channel_type_idintegerContatos com canal deste tipo (WhatsApp, Instagram…).
origin_idintegerContatos com canal desta origem.
updated_sincedata ISO 8601Contatos alterados a partir desta data (nome, e-mail, descrição) — para sincronização incremental.
page / per_pageintegerPaginação; per_page de 1 a 100 (default 25).
GET https://api.atys.pro/api/v1/contacts Buscar contatos

Exemplos de código — buscar contatos

cURL
curl "https://api.atys.pro/api/v1/contacts?q=maria&tag_ids%5B%5D=9&per_page=25" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": [
    {
      "id": 5120,
      "name": "Maria Cliente",
      "email": "maria@cliente.com.br",
      "description": null,
      "kind": "person",
      "organization_id": null,
      "is_group": false,
      "channels": [
        {
          "id": 77120,
          "contact_id": 5120,
          "name": "Maria Cliente",
          "key": "5511988887777",
          "is_group": false,
          "channel_type": {
            "id": 3,
            "name": "CHANNEL_TYPE_OFC_WHATSAPP",
            "description": "Whatsapp oficial"
          },
          "company_channel": {
            "id": 44,
            "name": "WhatsApp da Loja"
          },
          "origin": {
            "id": 4,
            "name": "CONTACT_ORIGIN_API"
          },
          "sector": null,
          "assigned_user": null,
          "status_id": null,
          "tags": [
            {
              "id": 9,
              "name": "VIP",
              "color": "#f59e0b"
            }
          ],
          "last_message_at": "2026-11-04T15:20:00-03:00",
          "created_at": "2026-11-04T15:20:00-03:00",
          "updated_at": "2026-11-04T15:20:00-03:00"
        }
      ],
      "created_at": "2026-11-04T15:20:00-03:00",
      "updated_at": "2026-11-04T15:20:00-03:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "last_page": 1
  }
}

Localizar por telefone ou e-mail

Atalho para achar o id de um contato antes de criar um negócio no CRM ou um evento na Agenda. Informe phone (com ou sem DDI, máscara e 9º dígito) e/ou email (sem diferenciar maiúsculas). Devolve o primeiro contato visível que casar ou 404.

GET https://api.atys.pro/api/v1/contacts/lookup Localizar contato

Exemplos de código — localizar contato

cURL
curl "https://api.atys.pro/api/v1/contacts/lookup?phone=11988887777" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": {
    "id": 5120,
    "name": "Maria Cliente",
    "email": "maria@cliente.com.br",
    "description": null,
    "kind": "person",
    "organization_id": null,
    "is_group": false,
    "channels": [
      {
        "id": 77120,
        "contact_id": 5120,
        "name": "Maria Cliente",
        "key": "5511988887777",
        "is_group": false,
        "channel_type": {
          "id": 3,
          "name": "CHANNEL_TYPE_OFC_WHATSAPP",
          "description": "Whatsapp oficial"
        },
        "company_channel": {
          "id": 44,
          "name": "WhatsApp da Loja"
        },
        "origin": {
          "id": 4,
          "name": "CONTACT_ORIGIN_API"
        },
        "sector": null,
        "assigned_user": null,
        "status_id": null,
        "tags": [
          {
            "id": 9,
            "name": "VIP",
            "color": "#f59e0b"
          }
        ],
        "last_message_at": "2026-11-04T15:20:00-03:00",
        "created_at": "2026-11-04T15:20:00-03:00",
        "updated_at": "2026-11-04T15:20:00-03:00"
      }
    ],
    "created_at": "2026-11-04T15:20:00-03:00",
    "updated_at": "2026-11-04T15:20:00-03:00"
  }
}

Ver um contato

O contato com os canais visíveis. Os dados seguem as permissões do usuário API na plataforma: sem ver nome completo só o primeiro nome, sem ver número o identificador mascarado e sem ver e-mail só o domínio.

GET https://api.atys.pro/api/v1/contacts/{id} Detalhe do contato

Exemplos de código — detalhe do contato

cURL
curl "https://api.atys.pro/api/v1/contacts/5120" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": {
    "id": 5120,
    "name": "Maria Cliente",
    "email": "maria@cliente.com.br",
    "description": null,
    "kind": "person",
    "organization_id": null,
    "is_group": false,
    "channels": [
      {
        "id": 77120,
        "contact_id": 5120,
        "name": "Maria Cliente",
        "key": "5511988887777",
        "is_group": false,
        "channel_type": {
          "id": 3,
          "name": "CHANNEL_TYPE_OFC_WHATSAPP",
          "description": "Whatsapp oficial"
        },
        "company_channel": {
          "id": 44,
          "name": "WhatsApp da Loja"
        },
        "origin": {
          "id": 4,
          "name": "CONTACT_ORIGIN_API"
        },
        "sector": null,
        "assigned_user": null,
        "status_id": null,
        "tags": [
          {
            "id": 9,
            "name": "VIP",
            "color": "#f59e0b"
          }
        ],
        "last_message_at": "2026-11-04T15:20:00-03:00",
        "created_at": "2026-11-04T15:20:00-03:00",
        "updated_at": "2026-11-04T15:20:00-03:00"
      }
    ],
    "created_at": "2026-11-04T15:20:00-03:00",
    "updated_at": "2026-11-04T15:20:00-03:00"
  }
}

Editar contato

Envie só o que muda: name, email e description. E-mail já usado por outro contato da empresa responde 422 email_taken. Canais, campos e etiquetas têm endpoints próprios.

PATCH https://api.atys.pro/api/v1/contacts/{id} Editar contato

Exemplos de código — editar contato

cURL
curl -X PATCH "https://api.atys.pro/api/v1/contacts/5120" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Silva",
    "description": "Cliente desde 2024"
  }'
200 OK
{
  "data": {
    "id": 5120,
    "name": "Maria Silva",
    "email": "maria@cliente.com.br",
    "description": "Cliente desde 2024",
    "kind": "person",
    "organization_id": null,
    "is_group": false,
    "channels": [
      {
        "id": 77120,
        "contact_id": 5120,
        "name": "Maria Cliente",
        "key": "5511988887777",
        "is_group": false,
        "channel_type": {
          "id": 3,
          "name": "CHANNEL_TYPE_OFC_WHATSAPP",
          "description": "Whatsapp oficial"
        },
        "company_channel": {
          "id": 44,
          "name": "WhatsApp da Loja"
        },
        "origin": {
          "id": 4,
          "name": "CONTACT_ORIGIN_API"
        },
        "sector": null,
        "assigned_user": null,
        "status_id": null,
        "tags": [
          {
            "id": 9,
            "name": "VIP",
            "color": "#f59e0b"
          }
        ],
        "last_message_at": "2026-11-04T15:20:00-03:00",
        "created_at": "2026-11-04T15:20:00-03:00",
        "updated_at": "2026-11-04T15:20:00-03:00"
      }
    ],
    "created_at": "2026-11-04T15:20:00-03:00",
    "updated_at": "2026-11-04T15:20:00-03:00"
  }
}

Canais do contato

Um contato pode estar em vários canais da empresa (o mesmo cliente no WhatsApp da loja e no Instagram). É no canal que ficam atendente, setor, etiquetas, origem e a conversa. A lista traz só os canais visíveis; também é possível ver um canal pelo id.

GET https://api.atys.pro/api/v1/contacts/{id}/channels Listar canais do contato

Exemplos de código — listar canais do contato

cURL
curl "https://api.atys.pro/api/v1/contacts/5120/channels" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": [
    {
      "id": 77120,
      "contact_id": 5120,
      "name": "Maria Cliente",
      "key": "5511988887777",
      "is_group": false,
      "channel_type": {
        "id": 3,
        "name": "CHANNEL_TYPE_OFC_WHATSAPP",
        "description": "Whatsapp oficial"
      },
      "company_channel": {
        "id": 44,
        "name": "WhatsApp da Loja"
      },
      "origin": {
        "id": 4,
        "name": "CONTACT_ORIGIN_API"
      },
      "sector": null,
      "assigned_user": null,
      "status_id": null,
      "tags": [
        {
          "id": 9,
          "name": "VIP",
          "color": "#f59e0b"
        }
      ],
      "last_message_at": "2026-11-04T15:20:00-03:00",
      "created_at": "2026-11-04T15:20:00-03:00",
      "updated_at": "2026-11-04T15:20:00-03:00"
    },
    {
      "id": 77131,
      "contact_id": 5120,
      "name": "Maria (WhatsApp)",
      "key": "552177776666",
      "is_group": false,
      "channel_type": {
        "id": 2,
        "name": "CHANNEL_TYPE_WHATSAPP",
        "description": "Whatsapp"
      },
      "company_channel": {
        "id": 45,
        "name": "Comercial"
      },
      "origin": {
        "id": 4,
        "name": "CONTACT_ORIGIN_API"
      },
      "sector": {
        "id": 6,
        "name": "Comercial"
      },
      "assigned_user": {
        "id": 81,
        "name": "Ana Atendente"
      },
      "status_id": null,
      "tags": [],
      "last_message_at": "2026-11-04T15:20:00-03:00",
      "created_at": "2026-11-04T15:20:00-03:00",
      "updated_at": "2026-11-04T15:20:00-03:00"
    }
  ]
}
GET https://api.atys.pro/api/v1/contacts/{id}/channels/{channelId} Ver canal do contato

Exemplos de código — ver canal do contato

cURL
curl "https://api.atys.pro/api/v1/contacts/5120/channels/77120" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": {
    "id": 77120,
    "contact_id": 5120,
    "name": "Maria Cliente",
    "key": "5511988887777",
    "is_group": false,
    "channel_type": {
      "id": 3,
      "name": "CHANNEL_TYPE_OFC_WHATSAPP",
      "description": "Whatsapp oficial"
    },
    "company_channel": {
      "id": 44,
      "name": "WhatsApp da Loja"
    },
    "origin": {
      "id": 4,
      "name": "CONTACT_ORIGIN_API"
    },
    "sector": null,
    "assigned_user": null,
    "status_id": null,
    "tags": [
      {
        "id": 9,
        "name": "VIP",
        "color": "#f59e0b"
      }
    ],
    "last_message_at": "2026-11-04T15:20:00-03:00",
    "created_at": "2026-11-04T15:20:00-03:00",
    "updated_at": "2026-11-04T15:20:00-03:00"
  }
}

Adicionar canal ao contato

Liga um contato existente a mais um canal da empresa, com a mesma normalização do identificador da criação. Repetir o mesmo canal e identificador devolve o canal existente (200 OK). Se o identificador já é de outro contato naquele canal, responde 422 channel_key_in_use; se for de outro contato em outro canal da empresa, a plataforma mantém a pessoa unificada e o canal novo fica naquele contato (confira o contact_id da resposta).

CampoTipoObrigatórioDescrição
company_channel_idintegerSimUm dos canais da empresa.
keystring (50)SimIdentificador no canal.
namestringNãoNome do contato no canal; default o nome do contato.
user_id / sector_idintegerNãoAtendente e setor iniciais.
tag_idsinteger[]NãoEtiquetas do canal.
POST https://api.atys.pro/api/v1/contacts/{id}/channels Adicionar canal

Exemplos de código — adicionar canal

cURL
curl -X POST "https://api.atys.pro/api/v1/contacts/5120/channels" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "company_channel_id": 45,
    "key": "5521977776666",
    "name": "Maria (WhatsApp)",
    "user_id": 81,
    "sector_id": 6
  }'
201 Created
{
  "data": {
    "id": 77131,
    "contact_id": 5120,
    "name": "Maria (WhatsApp)",
    "key": "552177776666",
    "is_group": false,
    "channel_type": {
      "id": 2,
      "name": "CHANNEL_TYPE_WHATSAPP",
      "description": "Whatsapp"
    },
    "company_channel": {
      "id": 45,
      "name": "Comercial"
    },
    "origin": {
      "id": 4,
      "name": "CONTACT_ORIGIN_API"
    },
    "sector": {
      "id": 6,
      "name": "Comercial"
    },
    "assigned_user": {
      "id": 81,
      "name": "Ana Atendente"
    },
    "status_id": null,
    "tags": [],
    "last_message_at": "2026-11-04T15:20:00-03:00",
    "created_at": "2026-11-04T15:20:00-03:00",
    "updated_at": "2026-11-04T15:20:00-03:00"
  }
}

Editar canal do contato

O que o modal Editar canal da tela edita — envie só o que muda: key, name, company_channel_id (outro canal da empresa do mesmo tipo), user_id e sector_id (null tira o atendente/setor). Novo número de WhatsApp é verificado; identificador já usado naquele canal responde 422. Em grupos não é possível mudar o identificador nem o canal da empresa (422 group_channel_locked).

PATCH https://api.atys.pro/api/v1/contacts/{id}/channels/{channelId} Editar canal do contato

Exemplos de código — editar canal do contato

cURL
curl -X PATCH "https://api.atys.pro/api/v1/contacts/5120/channels/77131" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria WhatsApp",
    "user_id": null
  }'
200 OK
{
  "data": {
    "id": 77131,
    "contact_id": 5120,
    "name": "Maria WhatsApp",
    "key": "552177776666",
    "is_group": false,
    "channel_type": {
      "id": 2,
      "name": "CHANNEL_TYPE_WHATSAPP",
      "description": "Whatsapp"
    },
    "company_channel": {
      "id": 45,
      "name": "Comercial"
    },
    "origin": {
      "id": 4,
      "name": "CONTACT_ORIGIN_API"
    },
    "sector": {
      "id": 6,
      "name": "Comercial"
    },
    "assigned_user": null,
    "status_id": null,
    "tags": [],
    "last_message_at": "2026-11-04T15:20:00-03:00",
    "created_at": "2026-11-04T15:20:00-03:00",
    "updated_at": "2026-11-04T15:20:00-03:00"
  }
}

Campos personalizados do contato

A plataforma guarda campos personalizados em dois lugares: no contato (a ficha do contato no CRM) e no canal do contato (a tela de Contatos e o painel lateral do atendimento — veja campos do canal). Estes endpoints leem e gravam os do contato. O PUT recebe fields: [{field_id, value}] e grava só os campos enviados; valor vazio ou null apaga o campo. Os valores são validados e normalizados pelo tipo (CPF/CNPJ e telefone só dígitos, data AAAA-MM-DD…); fora do formato responde 422 invalid_custom_field_value.

GET https://api.atys.pro/api/v1/contacts/{id}/custom-fields Ver campos do contato

Exemplos de código — ver campos do contato

cURL
curl "https://api.atys.pro/api/v1/contacts/5120/custom-fields" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": [
    {
      "field_id": 56,
      "name": "Loja",
      "type": "text",
      "value": "Loja Centro"
    }
  ]
}
PUT https://api.atys.pro/api/v1/contacts/{id}/custom-fields Gravar campos do contato

Exemplos de código — gravar campos do contato

cURL
curl -X PUT "https://api.atys.pro/api/v1/contacts/5120/custom-fields" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {
        "field_id": 56,
        "value": "Loja Centro"
      },
      {
        "field_id": 57,
        "value": null
      }
    ]
  }'
200 OK
{
  "data": [
    {
      "field_id": 56,
      "name": "Loja",
      "type": "text",
      "value": "Loja Centro"
    }
  ]
}

Campos personalizados do canal

Os campos que a equipe vê e edita na tela de Contatos e no atendimento, gravados pela mesma rotina da tela. Mesmo formato e mesmas regras dos campos do contato.

GET https://api.atys.pro/api/v1/contacts/{id}/channels/{channelId}/custom-fields Ver campos do canal

Exemplos de código — ver campos do canal

cURL
curl "https://api.atys.pro/api/v1/contacts/5120/channels/77120/custom-fields" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": [
    {
      "field_id": 55,
      "name": "CPF",
      "type": "cpf_cnpj",
      "value": "52998224725"
    }
  ]
}
PUT https://api.atys.pro/api/v1/contacts/{id}/channels/{channelId}/custom-fields Gravar campos do canal

Exemplos de código — gravar campos do canal

cURL
curl -X PUT "https://api.atys.pro/api/v1/contacts/5120/channels/77120/custom-fields" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {
        "field_id": 55,
        "value": "529.982.247-25"
      }
    ]
  }'
200 OK
{
  "data": [
    {
      "field_id": 55,
      "name": "CPF",
      "type": "cpf_cnpj",
      "value": "52998224725"
    }
  ]
}

Etiquetas do canal

As etiquetas de atendimento ficam no canal do contato. tag_ids substitui o conjunto (envie [] para limpar); etiquetas que o usuário API não enxerga e já estavam no canal são preservadas. As automações de etiqueta atribuída/removida disparam e, no WhatsApp Business, a etiqueta correspondente é sincronizada — como na tela. Para etiquetar muitos contatos de uma vez, use as ações em lote.

PUT https://api.atys.pro/api/v1/contacts/{id}/channels/{channelId}/tags Definir etiquetas do canal

Exemplos de código — definir etiquetas do canal

cURL
curl -X PUT "https://api.atys.pro/api/v1/contacts/5120/channels/77120/tags" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_ids": [9]
  }'
200 OK
{
  "data": {
    "id": 77120,
    "contact_id": 5120,
    "name": "Maria Cliente",
    "key": "5511988887777",
    "is_group": false,
    "channel_type": {
      "id": 3,
      "name": "CHANNEL_TYPE_OFC_WHATSAPP",
      "description": "Whatsapp oficial"
    },
    "company_channel": {
      "id": 44,
      "name": "WhatsApp da Loja"
    },
    "origin": {
      "id": 4,
      "name": "CONTACT_ORIGIN_API"
    },
    "sector": null,
    "assigned_user": null,
    "status_id": null,
    "tags": [
      {
        "id": 9,
        "name": "VIP",
        "color": "#f59e0b"
      }
    ],
    "last_message_at": "2026-11-04T15:20:00-03:00",
    "created_at": "2026-11-04T15:20:00-03:00",
    "updated_at": "2026-11-04T15:20:00-03:00"
  }
}

Excluir canal do contato

O mesmo que Apagar contato numa linha da tela: apaga o canal, a conversa dele e os campos personalizados do canal. Se era o último canal, o contato também é excluído. Irreversível.

DELETE https://api.atys.pro/api/v1/contacts/{id}/channels/{channelId} Excluir canal do contato

Exemplos de código — excluir canal do contato

cURL
curl -X DELETE "https://api.atys.pro/api/v1/contacts/5120/channels/77131" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"

Excluir contato

Exclui o contato com todos os canais e conversas. Se o contato tiver algum canal que o usuário API não enxerga, nada é excluído e a resposta é 422 contact_has_hidden_channels — exclua os canais visíveis individualmente. Irreversível.

DELETE https://api.atys.pro/api/v1/contacts/{id} Excluir contato

Exemplos de código — excluir contato

cURL
curl -X DELETE "https://api.atys.pro/api/v1/contacts/5120" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"

Ações em lote: seleção, filtros e fila

São as ações do menu da tela de Contatos: atribuir atendente, transferir de canal, etiquetar, encerrar conversas, excluir, importar e exportar. Elas agem sobre os canais do contato (as linhas da tela): os ids aceitos são contact_channel_ids, até 500 por chamada.

Transferir, etiquetar e exportar aceitam duas formas de escolher os canais:

  • Por ids (contact_channel_ids) — a ação roda na hora e responde 200 com o resultado. Se algum id não for da sua empresa ou estiver fora da visibilidade do usuário API, nada é feito: a resposta é 422 invalid_ids com a lista em details.invalid_ids.
  • Por filtros ("scope": "filtered" + filters) — como "todos os filtrados" na tela. A ação entra na fila e responde 202 Accepted com um operation_id. Sem filtros, vale para todos os canais que o usuário API enxerga.
Filtro (filters.*)TipoDescrição
searchstringBusca por nome, e-mail ou telefone, como a busca da tela.
company_channel_idintegerCanal da empresa (o WhatsApp da loja, por exemplo).
origin_idintegerOrigem do contato.
user_id / without_userinteger / booleanAtendente responsável, ou só os sem atendente.
sector_id / without_sectorinteger / booleanSetor, ou só os sem setor.
status_idintegerStatus da conversa.
tag_ids + tag_matcharray de integer + stringEtiquetas de contato; any (default) = qualquer uma, all = todas.
created_from / created_todate (AAAA-MM-DD)Período de criação (os dois juntos).
updated_from / updated_todate (AAAA-MM-DD)Período da última atualização (os dois juntos).

Acompanhe uma operação em fila pelo operation_id. status vai de processing a completed; result traz as contagens da ação (transferidos, alterados, encerrados…). O status fica disponível por 24 horas e só para a chave do usuário que iniciou a operação.

GET https://api.atys.pro/api/v1/contacts/bulk/{operationId} Status de uma ação em lote

Exemplos de código — status de uma ação em lote

cURL
curl "https://api.atys.pro/api/v1/contacts/bulk/trf_6543a1b2c3d4e5.12345678" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": {
    "operation_id": "trf_6543a1b2c3d4e5.12345678",
    "operation": "transfer",
    "status": "completed",
    "total": 1240,
    "result": {
      "transferred": 1198,
      "merged": 12,
      "skipped": 30,
      "failed": 0
    },
    "started_at": "2026-11-04T16:20:00-03:00",
    "completed_at": "2026-11-04T16:23:41-03:00"
  }
}

operation é transfer, tags_add, tags_remove ou close. Ao terminar, a importação também dispara o webhook contact.import.completed.

Motivos de encerramento

Todo encerramento de conversa pede um motivo, e cada canal tem os seus (os três do sistema — Resolvido, Parou de responder e Spam — e os criados pela equipe). has_satisfaction_survey indica se, encerrando com esse motivo, a pesquisa de satisfação é enviada pelo usuário API. Filtre por company_channel_id; a lista é paginada (page, per_page até 100).

GET https://api.atys.pro/api/v1/contacts/close-reasons Listar motivos de encerramento

Exemplos de código — listar motivos de encerramento

cURL
curl "https://api.atys.pro/api/v1/contacts/close-reasons?company_channel_id=44" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": [
    {
      "id": 812,
      "text": "Resolvido",
      "slug": "resolved",
      "is_system": true,
      "company_channel_id": 44,
      "has_satisfaction_survey": true
    },
    {
      "id": 815,
      "text": "Venda concluída",
      "slug": null,
      "is_system": false,
      "company_channel_id": 44,
      "has_satisfaction_survey": false
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 2,
    "last_page": 1
  }
}

Para criar um motivo novo num canal, como o "Novo motivo de encerramento" do modal: company_channel_id e text (até 100 caracteres). O canal precisa ser um dos canais do usuário API (invalid_company_channel).

POST https://api.atys.pro/api/v1/contacts/close-reasons Criar motivo de encerramento

Exemplos de código — criar motivo de encerramento

cURL
curl -X POST "https://api.atys.pro/api/v1/contacts/close-reasons" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "company_channel_id": 44,
    "text": "Venda concluída"
  }'
201 Created
{
  "data": {
    "id": 815,
    "text": "Venda concluída",
    "slug": null,
    "is_system": false,
    "company_channel_id": 44,
    "has_satisfaction_survey": false
  }
}

Atribuir atendente em lote

Define o atendente (e, opcionalmente, o setor) de vários canais de uma vez — "Atribuir contato ao atendente" na tela. O atendente precisa ser um usuário da empresa (invalid_user) e, com sector_id, pertencer ao setor (user_not_in_sector). Grupos não têm atendente: são ignorados e voltam em skipped_group_ids. Só por ids.

POST https://api.atys.pro/api/v1/contacts/bulk/assign Atribuir atendente

Exemplos de código — atribuir atendente

cURL
curl -X POST "https://api.atys.pro/api/v1/contacts/bulk/assign" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_channel_ids": [9120, 9121, 9122],
    "user_id": 77,
    "sector_id": 12
  }'
200 OK
{
  "data": {
    "updated": 3,
    "skipped_group_ids": [],
    "user": {
      "id": 77,
      "name": "Carla Atendente"
    },
    "sector_id": 12
  }
}

Transferir para outro canal

Move as conversas para outro canal da empresa do mesmo tipo (WhatsApp para WhatsApp, por exemplo) — "Transferir para outro canal" na tela. O canal de destino precisa estar entre os canais do usuário API, a menos que ele tenha a permissão de transferir para qualquer canal.

CampoTipoObrigatórioDescrição
target_company_channel_idintegerSimCanal de destino.
contact_channel_idsarray de integerSem scopeAté 500 canais do contato.
scope + filtersstring + objetoNãofiltered para usar os filtros (em fila).
transfer_messagesbooleanNãoLeva o histórico de mensagens junto. Default false.
confirm_mergebooleanNãoSe o contato já existe no destino, mescla as duas conversas. Sem isso, esses casos são ignorados.

Grupos, tipos de canal incompatíveis, conversas que já estão no destino e conflitos sem mesclagem são ignorados e aparecem nas contagens skipped_*.

POST https://api.atys.pro/api/v1/contacts/bulk/transfer Transferir canais selecionados

Exemplos de código — transferir canais selecionados

cURL
curl -X POST "https://api.atys.pro/api/v1/contacts/bulk/transfer" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_channel_ids": [9120, 9121, 9122],
    "target_company_channel_id": 51,
    "transfer_messages": true,
    "confirm_merge": false
  }'
200 OK
{
  "data": {
    "transferred": 2,
    "merged": 0,
    "skipped_group": 0,
    "skipped_incompatible_type": 0,
    "skipped_same_channel": 0,
    "skipped_needs_merge": 1
  }
}
POST https://api.atys.pro/api/v1/contacts/bulk/transfer Transferir pelos filtros

Exemplos de código — transferir pelos filtros

cURL
curl -X POST "https://api.atys.pro/api/v1/contacts/bulk/transfer" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "filtered",
    "filters": {
      "company_channel_id": 44,
      "without_user": true
    },
    "target_company_channel_id": 51
  }'
202 Accepted
{
  "data": {
    "operation_id": "trf_6543a1b2c3d4e5.12345678",
    "status": "processing",
    "total": 1240
  }
}

Adicionar ou remover etiquetas

"Adicionar etiquetas" e "Remover etiquetas" da tela: action é add ou remove e tag_ids são etiquetas de contato (até 50) que o usuário API pode usar — senão 422 invalid_tag_ids e nada muda. Etiquetas sincronizadas com o WhatsApp não podem ser alteradas em massa.

Por padrão, etiquetar em lote não dispara as automações das etiquetas (workflows e conversões de anúncio). Para disparar, envie "run_automations": true. changed conta os canais que mudaram; unchanged, os que já tinham (ou não tinham) as etiquetas.

POST https://api.atys.pro/api/v1/contacts/bulk/tags Etiquetar canais selecionados

Exemplos de código — etiquetar canais selecionados

cURL
curl -X POST "https://api.atys.pro/api/v1/contacts/bulk/tags" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add",
    "tag_ids": [310, 311],
    "contact_channel_ids": [9120, 9121, 9122]
  }'
200 OK
{
  "data": {
    "action": "add",
    "changed": 3,
    "unchanged": 0
  }
}
POST https://api.atys.pro/api/v1/contacts/bulk/tags Remover etiqueta pelos filtros

Exemplos de código — remover etiqueta pelos filtros

cURL
curl -X POST "https://api.atys.pro/api/v1/contacts/bulk/tags" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "remove",
    "tag_ids": [310],
    "scope": "filtered",
    "filters": {
      "company_channel_id": 44,
      "tag_ids": [310],
      "created_from": "2026-10-01",
      "created_to": "2026-10-31"
    }
  }'
202 Accepted
{
  "data": {
    "operation_id": "tag_6543a1b2c3d4e7.55667788",
    "status": "processing",
    "total": 860
  }
}

Encerrar conversas

Encerra conversas de um canal com um motivo do próprio canal (invalid_close_reason se não for). Conversas já encerradas e grupos são ignorados.

  • Com contact_channel_ids — encerra só esses canais, na hora. Todos precisam ser do company_channel_id informado.
  • Sem ids — encerra todas as conversas abertas do canal, em fila, como o "Encerrar conversas" da tela. Só nesse modo dá para enviar a pesquisa de satisfação (send_satisfaction_survey); com ids, o pedido volta survey_requires_whole_channel.

Antes de encerrar o canal inteiro, a prévia mostra se o motivo envia a pesquisa, por onde (chat ou email) e para quantas conversas: só contatos que escreveram nas últimas recent_hours horas recebem, até max_surveys por encerramento, enviadas aos poucos.

GET https://api.atys.pro/api/v1/contacts/bulk/close/survey-preview Prévia do encerramento do canal

Exemplos de código — prévia do encerramento do canal

cURL
curl "https://api.atys.pro/api/v1/contacts/bulk/close/survey-preview?company_channel_id=44&close_reason_id=812" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": {
    "survey_available": true,
    "reason": null,
    "via": "chat",
    "open_conversations": 318,
    "eligible": 42,
    "recent_hours": 24,
    "max_surveys": 200
  }
}
POST https://api.atys.pro/api/v1/contacts/bulk/close Encerrar canais selecionados

Exemplos de código — encerrar canais selecionados

cURL
curl -X POST "https://api.atys.pro/api/v1/contacts/bulk/close" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "company_channel_id": 44,
    "close_reason_id": 812,
    "contact_channel_ids": [9120, 9121, 9122]
  }'
200 OK
{
  "data": {
    "closed": 3,
    "skipped_groups": 0
  }
}
POST https://api.atys.pro/api/v1/contacts/bulk/close Encerrar todas as conversas do canal

Exemplos de código — encerrar todas as conversas do canal

cURL
curl -X POST "https://api.atys.pro/api/v1/contacts/bulk/close" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "company_channel_id": 44,
    "close_reason_id": 812,
    "send_satisfaction_survey": true
  }'
202 Accepted
{
  "data": {
    "operation_id": "cls_6543a1b2c3d4e8.99887766",
    "status": "processing",
    "total": 318
  }
}

Excluir em lote

Exclui os canais do contato e, quando o contato fica sem nenhum canal, o próprio contato — com as conversas e os campos personalizados do canal. Não tem volta. Só por ids (até 500): a exclusão por filtros ou da empresa inteira, que existe na tela, não é oferecida pela API. Exige a permissão Excluir contatos na chave.

POST https://api.atys.pro/api/v1/contacts/bulk/delete Excluir canais selecionados

Exemplos de código — excluir canais selecionados

cURL
curl -X POST "https://api.atys.pro/api/v1/contacts/bulk/delete" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_channel_ids": [9120, 9121, 9122]
  }'
200 OK
{
  "data": {
    "deleted_channels": 3,
    "deleted_contacts": 2,
    "contact_channel_ids": [
      9120,
      9121,
      9122
    ]
  }
}

Importar contatos

A mesma importação do modal "Importar contatos", com as colunas da planilha em JSON: name e phone obrigatórios, email opcional. Até 5.000 linhas por chamada, num canal da empresa que seja um dos canais do usuário API (Minichat não aceita importação: unsupported_channel).

  • O telefone pode vir com espaços, traços, parênteses e +; vale só os dígitos. Com "number_type": "national", números sem o 55 ganham o código do Brasil.
  • Telefone que já existe no canal é contado em duplicates e não muda. Se o telefone ou o e-mail já pertencem a um contato da empresa, o canal novo é ligado a ele.
  • Num canal de WhatsApp com até 50 números, eles são conferidos no WhatsApp; os que não existem entram em invalid.

Até 100 linhas a importação roda na hora e responde 200 com as contagens. Acima disso, entra na fila e responde 202 Accepted com o import_id.

POST https://api.atys.pro/api/v1/contacts/import Importar contatos

Exemplos de código — importar contatos

cURL
curl -X POST "https://api.atys.pro/api/v1/contacts/import" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "company_channel_id": 44,
    "number_type": "national",
    "contacts": [
      {
        "name": "Maria Cliente",
        "phone": "(11) 98888-0001",
        "email": "maria@cliente.com.br"
      },
      {
        "name": "João Comprador",
        "phone": "11988880002"
      }
    ]
  }'
200 OK
{
  "data": {
    "import_id": null,
    "status": "completed",
    "total": 2,
    "imported": 1,
    "duplicates": 1,
    "invalid": 0,
    "failed": 0
  }
}
202 Accepted (mais de 100 linhas)
{
    "data": {
        "import_id": "import_6543a1b2c3d4f0.87654321",
        "status": "processing",
        "total": 3200
    }
}

Acompanhe pelo import_id (24 horas, só a chave de quem importou). skipped soma duplicados e inválidos; status termina em completed ou failed (com error). O webhook contact.import.completed também avisa o fim.

GET https://api.atys.pro/api/v1/contacts/import/{importId} Status da importação

Exemplos de código — status da importação

cURL
curl "https://api.atys.pro/api/v1/contacts/import/import_6543a1b2c3d4f0.87654321" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": {
    "import_id": "import_6543a1b2c3d4f0.87654321",
    "status": "processing",
    "total": 3200,
    "processed": 1500,
    "imported": 1421,
    "skipped": 74,
    "failed": 5,
    "error": null,
    "started_at": "2026-11-04T16:30:00-03:00"
  }
}

Exportar contatos

Gera a mesma planilha .xlsx do "Exportar contatos" da tela, por ids ou pelos filtros. fields escolhe as colunas, na ordem: name, email, phone, channel, company_channel, origin, attendant, sector, created_at, updated_at e tags. Nome completo, telefone e e-mail seguem as permissões do usuário API (sem elas, saem abreviados ou mascarados). Até 50.000 linhas por exportação (export_too_large); sem nenhuma, nothing_to_export.

Até 1.000 linhas o arquivo fica pronto na hora (200, com o download_token); acima disso, a exportação entra na fila (202 Accepted) e o token aparece no status.

POST https://api.atys.pro/api/v1/contacts/export Exportar contatos

Exemplos de código — exportar contatos

cURL
curl -X POST "https://api.atys.pro/api/v1/contacts/export" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": ["name", "email", "phone", "attendant", "tags"],
    "scope": "filtered",
    "filters": {
      "company_channel_id": 44,
      "tag_ids": [310],
      "created_from": "2026-10-01",
      "created_to": "2026-10-31"
    }
  }'
200 OK
{
  "data": {
    "export_id": null,
    "status": "completed",
    "total": 312,
    "download_token": "3f6c2a9e-8d41-4b7a-9c55-1e2f3a4b5c6d",
    "expires_at": "2026-11-04T17:40:00-03:00"
  }
}
202 Accepted (mais de 1.000 linhas)
{
    "data": {
        "export_id": "export_6543a1b2c3d4f9.11223344",
        "status": "processing",
        "total": 18450
    }
}
GET https://api.atys.pro/api/v1/contacts/export/{exportId} Status da exportação

Exemplos de código — status da exportação

cURL
curl "https://api.atys.pro/api/v1/contacts/export/export_6543a1b2c3d4f9.11223344" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"
200 OK
{
  "data": {
    "export_id": "export_6543a1b2c3d4f9.11223344",
    "status": "completed",
    "total": 18450,
    "download_token": "3f6c2a9e-8d41-4b7a-9c55-1e2f3a4b5c6d",
    "expires_at": "2026-11-04T17:52:00-03:00",
    "started_at": "2026-11-04T16:50:00-03:00",
    "completed_at": "2026-11-04T16:52:10-03:00",
    "error": null
  }
}

O download devolve o arquivo (Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet), não JSON. O token vale 60 minutos e um único download, só com a chave de quem exportou; depois disso, 404 — gere a exportação de novo.

GET https://api.atys.pro/api/v1/contacts/export/{token}/download Baixar a planilha

Exemplos de código — baixar a planilha

cURL
curl "https://api.atys.pro/api/v1/contacts/export/3f6c2a9e-8d41-4b7a-9c55-1e2f3a4b5c6d/download" \
  -H "Authorization: Bearer atys_live_SUA_CHAVE" \
  -H "Accept: application/json"

Erros

Todo erro da v1 tem o mesmo formato: {"error": {"code", "message", "details"}}. Use o code no seu tratamento; a message é para leitura humana.

422 validation_failed — dados inválidos

Campo obrigatório ausente ou com formato errado. details traz os erros por campo.

{
  "error": {
    "code": "validation_failed",
    "message": "The name field is required.",
    "details": { "name": ["The name field is required."] }
  }
}
422 invalid_ids / invalid_company_channel / invalid_user / invalid_sector / invalid_tag

Algum id não é da empresa ou não é visível para a chave. Nas ações em lote, details.invalid_ids lista quais — e nada é feito.

422 email_taken / channel_key_in_use / contact_has_hidden_channels / group_channel_locked

E-mail ou número já usado por outro contato, contato com canais que o usuário API não vê (não pode ser excluído inteiro), ou canal de grupo, que não é editável.

422 unknown_custom_field / invalid_custom_field_value / tags_require_channel

Campo personalizado inexistente ou valor no formato errado; etiquetas só existem no canal do contato.

422 invalid_whatsapp_number / whatsapp_validation_unavailable / unsupported_channel

O número não tem WhatsApp, não há WhatsApp conectado para validar, ou o canal não aceita importação.

422 user_not_in_sector / invalid_close_reason / survey_requires_whole_channel / export_too_large / nothing_to_export

Erros das ações em lote, da importação e da exportação — veja cada seção.

404 not_found

O contato, canal ou item não existe ou não é visível para a chave.

403 forbidden

A chave não tem a permissão de Contatos necessária, ou o usuário API não tem a permissão na plataforma.

401 unauthenticated

Chave ausente, inválida, revogada ou expirada.

Recebemos seu contato!

Um especialista da Atys vai falar com você em breve para agendar a demonstração.

Agendar demonstração

Em 20 minutos um especialista mostra a Atys na sua realidade.

BR +55