DoneTalk Desenvolvedores Entrar

Segmentos

Listar segmentos

GET /v1/c/{slug}/segments · Escopos: contacts:read · campaigns:write

Parâmetros do endereço

CampoDetalhes
slugO identificador da empresa no DoneTalk (o mesmo da chave).

Exemplo de pedido

curl -X GET "https://api.donetalk.com/v1/c/demo/segments" \
  -H "Authorization: Bearer $DONETALK_KEY"

Resposta 200

{
  "segments": [
    {
      "id": "01a1a0b0-1c2d-7e3f-8a9b-0c1d2e3f4a5b",
      "name": "Clientes do plano anual",
      "conditions": [
        {
          "field": "field.plano",
          "op": "eq",
          "value": "anual"
        }
      ],
      "count": 312,
      "updatedAt": "2026-10-23T13:02:11.000Z"
    }
  ]
}

Erros possíveis

  • 401 unauthorized
  • 403 insufficient_scope
  • 422 validation_failed
  • 429 rate_limited

Criar um segmento

POST /v1/c/{slug}/segments · Escopos: contacts:write

Um grupo de contatos por condições: etiqueta, origem, último desfecho, dias desde a última conversa ou o cadastro, consentimento de marketing, nome, WhatsApp e qualquer campo (field.<chave>).

Parâmetros do endereço

CampoDetalhes
slugO identificador da empresa no DoneTalk (o mesmo da chave).

Corpo do pedido

CampoTipoObrigatórioDetalhes
namestringsimaté 120 caracteres
conditionslista de objetosimaté 20
conditions[].fieldstringsimaté 80 caracteres
conditions[].opum de eq, neq, has, not_has, contains, empty, not_empty, gt, lt, nonesim
conditions[].valuestring · number · boolean · um de nullnão

Exemplo de pedido

curl -X POST "https://api.donetalk.com/v1/c/demo/segments" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Clientes do plano anual",
  "conditions": [
    {
      "field": "field.plano",
      "op": "eq",
      "value": "anual"
    }
  ]
}'

Resposta 201

{
  "segment": {
    "id": "01a1a0b0-1c2d-7e3f-8a9b-0c1d2e3f4a5b"
  }
}

Erros possíveis

  • 401 unauthorized
  • 403 insufficient_scope
  • 422 validation_failed
  • 429 rate_limited

Editar um segmento

PUT /v1/c/{slug}/segments/{id} · Escopos: contacts:write

Parâmetros do endereço

CampoDetalhes
slugO identificador da empresa no DoneTalk (o mesmo da chave).
idO id do registro.

Corpo do pedido

CampoTipoObrigatórioDetalhes
namestringsimaté 120 caracteres
conditionslista de objetosimaté 20
conditions[].fieldstringsimaté 80 caracteres
conditions[].opum de eq, neq, has, not_has, contains, empty, not_empty, gt, lt, nonesim
conditions[].valuestring · number · boolean · um de nullnão

Exemplo de pedido

curl -X PUT "https://api.donetalk.com/v1/c/demo/segments/:id" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Clientes do plano anual",
  "conditions": [
    {
      "field": "field.plano",
      "op": "eq",
      "value": "anual"
    }
  ]
}'

Resposta 200

{
  "ok": true
}

Erros possíveis

  • 401 unauthorized
  • 403 insufficient_scope
  • 422 validation_failed
  • 429 rate_limited

Apagar um segmento

DELETE /v1/c/{slug}/segments/{id} · Escopos: contacts:write

Parâmetros do endereço

CampoDetalhes
slugO identificador da empresa no DoneTalk (o mesmo da chave).
idO id do registro.

Exemplo de pedido

curl -X DELETE "https://api.donetalk.com/v1/c/demo/segments/:id" \
  -H "Authorization: Bearer $DONETALK_KEY"

Resposta 200

{
  "ok": true
}

Erros possíveis

  • 401 unauthorized
  • 403 insufficient_scope
  • 422 validation_failed
  • 429 rate_limited

Contar quem entra

POST /v1/c/{slug}/segments/count · Escopos: contacts:read · campaigns:write

Parâmetros do endereço

CampoDetalhes
slugO identificador da empresa no DoneTalk (o mesmo da chave).

Corpo do pedido

CampoTipoObrigatórioDetalhes
conditionslista de objetosimaté 20
conditions[].fieldstringsimaté 80 caracteres
conditions[].opum de eq, neq, has, not_has, contains, empty, not_empty, gt, lt, nonesim
conditions[].valuestring · number · boolean · um de nullnão

Exemplo de pedido

curl -X POST "https://api.donetalk.com/v1/c/demo/segments/count" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "conditions": [
    {
      "field": "tag",
      "op": "has",
      "value": "01a12150-3610-7c00-b680-188c2b4c7313"
    }
  ]
}'

Resposta 200

{
  "count": 312
}

Erros possíveis

  • 401 unauthorized
  • 403 insufficient_scope
  • 422 validation_failed
  • 429 rate_limited

Buscar contatos por condições

POST /v1/c/{slug}/contacts/search · Escopos: contacts:read

Parâmetros do endereço

CampoDetalhes
slugO identificador da empresa no DoneTalk (o mesmo da chave).

Corpo do pedido

CampoTipoObrigatórioDetalhes
segmentIdstring (uuid)não
conditionslista de objetonãoaté 20; default []
conditions[].fieldstringsimaté 80 caracteres
conditions[].opum de eq, neq, has, not_has, contains, empty, not_empty, gt, lt, nonesim
conditions[].valuestring · number · boolean · um de nullnão
qstringnãoaté 100 caracteres
limitintegernãoaté 200; mínimo 1; default 50
offsetintegernãoaté 1000000; default 0

Exemplo de pedido

curl -X POST "https://api.donetalk.com/v1/c/demo/contacts/search" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "conditions": [
    {
      "field": "marketing",
      "op": "eq",
      "value": "opted_in"
    }
  ],
  "limit": 50
}'

Resposta 200

{
  "total": 312,
  "marketingAllowed": 298,
  "contacts": [
    {
      "id": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
      "displayName": "Ana Souza",
      "source": "api",
      "fields": {
        "cpf": "529.982.247-25",
        "plano": "anual"
      },
      "isBlocked": false,
      "address": "5548999990001",
      "marketing": "opted_in",
      "lastOutcome": "converted",
      "tags": [
        {
          "id": "01a12150-3610-7c00-b680-188c2b4c7313",
          "name": {
            "pt-BR": "VIP",
            "en": "VIP",
            "es": "VIP"
          },
          "color": "#92400e"
        }
      ],
      "lastActivityAt": "2026-10-22T18:40:02.000Z",
      "createdAt": "2026-09-23T22:19:30.396Z"
    }
  ]
}

Erros possíveis

  • 401 unauthorized
  • 403 insufficient_scope
  • 422 validation_failed
  • 429 rate_limited

Esta página em Markdown