Pular para o conteúdo principal

API de Exportação de Dados

A API de Exportação de Dados permite pesquisar dados na Turn.io em um intervalo de datas especificado.

É uma abordagem em duas etapas:

  1. Crie um cursor com os parâmetros necessários para começar a obter dados.
  2. Solicite os dados de forma paginada usando o cursor.

Os seguintes tipos de dados estão disponíveis através da API de Exportação de Dados:

  • mensagens
  • detalhes de contato
  • status de mensagens

Parâmetros obrigatórios​

  • from: data e hora indicando o timestamp a partir do qual os dados devem ser recuperados.
  • until: data e hora indicando o timestamp até o qual os dados devem ser recuperados.

Parâmetros opcionais​

  • ordering: indica se o conjunto de resultados deve ser ordenado de forma ascendente ou descendente.
  • page_size: indica o número de registros desejados no conjunto de resultados.
  • scrubbing_rules: conjunto de regras possíveis para remover informações sensíveis de campos específicos na resposta JSON, apenas para mensagens e contatos. Atualmente, as regras suportadas incluem uma regra de busca e substituição com suporte a Expressões Regulares e uma regra de hashing.

Exportar Dados de Mensagens​

Criar um cursor para mensagens​

Para criar um cursor para começar a pesquisar mensagens, faça a seguinte requisição:

$ curl -X POST "https://whatsapp.turn.io/v1/data/messages/cursor" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -H "accept: application/vnd.v1+json" \
  -d '
    {
        "from": "2021-08-02T01:55:00.272Z",
        "until": "2021-08-20T01:55:00.272Z",
        "ordering": "desc",
        "page_size": 10,
        "scrubbing_rules": {
            "inbound": {
                "messages.text.body": {
                    "type": "regex",
                    "search": "world",
                    "replace": "XXXX"
                },
                "messages.from": {
                    "type": "hash"
                },
                "contacts.profile.name": {
                    "type": "hash"
                }
            },
            "outbound": {
                "text.body": {
                    "type": "regex",
                    "search": "world",
                    "replace": "XXXX"
                },
                "from": {
                    "type": "hash"
                }
            }
        }
    }'
> {
    "cursor": "<cursor>",
    "expires_at": "2021-08-30T17:47:18.318218Z"
}

Obter mensagens​

Para obter mensagens, faça a seguinte requisição:

$ curl -X GET "https://whatsapp.turn.io/v1/data/messages/cursor/<cursor>" \
    -H 'Authorization: Bearer token' \
    -H "Accept: application/vnd.v1+json" \
> {
    "data": [
        {
            "contacts": [
                {
                    "profile": {
                        "name": "SFMyNTY.KzMxNjIzNDU2NzAw.GSl886dfZXJ70DkFsUy39ij4QgYSceBw5UdV76Ugek0"
                    },
                    "wa_id": "01234567891"
                }
            ],
            "messages": [
                {
                    "_vnd": {
                        "v1": {
                            "author": {},
                            "chat": {
                                "assigned_to": null,
                                "owner": "+01234567891",
                                "permalink": "https://whatsapp.turn.io/app/col/63f0f404-08ee-423e-b571-01de718d4683",
                                "state": "OPEN",
                                "state_reason": null,
                                "unread_count": 0,
                                "uuid": "63f0f404-08ee-423e-b571-01de718d4683",
                                "contact_uuid": "b5b8f845-c526-4993-a8d3-464407ff3595",
                                "inserted_at": "2021-08-02T22:54:44.715101Z",
                                "updated_at": "2021-08-02T22:54:44.715101Z"
                            },
                            "direction": "inbound",
                            "faq_uuid": null,
                            "in_reply_to": null,
                            "inserted_at": "2021-08-02T22:54:44.715101Z",
                            "labels": [],
                            "rendered_content": null,
                            "uuid": "b2f8ed7f-09b4-fbad-57bb-81a42e37ba6c",
                            "last_status": "read",
                            "last_status_timestamp": "2021-08-02T22:54:44.721779Z",
                            "on_fallback_channel": false
                        }
                    },
                    "from": "SFMyNTY.MzE2MjM0NTY3MDA.nbfRbPvYvAqpKMOy19SwjrFZCz0Jb4IIxxaIc_4rx7s",
                    "id": "PksTrDovmBIG8SK8",
                    "text": {
                        "body": "hello XXXX 0"
                    },
                    "timestamp": "1627944884",
                    "type": "text"
                }
            ]
        },
        ...
    ],
    "paging": {
        "expires_at": "2021-08-30T18:49:26.761537Z",
        "next": "<next cursor>"
    }
}

As mensagens originais do WhatsApp são retornadas, mas incluem a chave _vnd específica da Turn.io em cada payload de mensagem com informações suplementares registradas pela Turn.io.

Se houver mais dados na próxima página, um cursor next será fornecido para continuar obtendo resultados. Caso contrário, significa que todos os resultados para os critérios de pesquisa fornecidos foram alcançados.

Exportar Detalhes de Contato​

Criar um cursor para detalhes de contato​

A exportação de dados de detalhes de contato difere no comportamento do endpoint de exportação de mensagens em um aspecto crucial. As mensagens são criadas uma vez e não são atualizadas - uma vez que uma mensagem é registrada no banco de dados, suas propriedades não mudam. Assim, paginamos pelo campo inserted_at.

No entanto, contatos e seus campos (por exemplo, um campo personalizado chamado current_savings) podem mudar ao longo do tempo. Se paginássemos por inserted_at, seria necessário paginar por todos os contatos a cada vez para obter os dados atualizados. Em vez disso, paginamos com base em quando os contatos foram atualizados.

Isso significa que o comportamento esperado seria solicitar dados diariamente ou semanalmente para um período de um dia ou uma semana, respectivamente - isso incluirá todas as informações atualizadas desde a última solicitação dos dados de contato. Não é necessário solicitar os dados usando um período de tempo desde o início para obter dados atualizados de contatos, a menos que você esteja solicitando pela primeira vez.

Para criar um cursor para começar a pesquisar detalhes de contato, faça a seguinte solicitação:

$ curl -X POST "https://whatsapp.turn.io/v1/data/contacts/cursor" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -H "accept: application/vnd.v1+json"
  -d '
    {
        "from": "2021-08-02T01:55:00.272Z",
        "until": "2021-08-20T01:55:00.272Z",
        "ordering": "desc",
        "page_size": 10,
        "scrubbing_rules": {
            "contact": {
                "details.name": {
                    "type": "regex",
                    "search": "Efrain",
                    "replace": "XXXX"
                },
                "details.surname": {
                    "type": "hash"
                }
            }
        }
    }'
> {
    "cursor": "<cursor>",
    "expires_at": "2021-08-30T17:47:18.318218Z"
}

Obter detalhes de contato​

Para obter detalhes de contato, faça a seguinte solicitação:

$ curl -X GET "https://whatsapp.turn.io/v1/data/contacts/cursor/<cursor>" \
    -H 'Authorization: Bearer token' \
    -H "Accept: application/vnd.v1+json" \
> {
    "data": [
        {
            "details": {
                "birthday": "1988-06-14T18:15:35.873852Z",
                "language": "ben",
                "location": null,
                "name": "XXXX",
                "opted_in": false,
                "opted_in_at": null,
                "surname": "SFMyNTY.UnVzc2Vs.fuONeooDjnkkCEtnLnT06Acs6xeuxnPZqhmscquTC-Y",
                "whatsapp_id": "31623456700",
                "whatsapp_profile_name": "pfannerstill"
            },
            "id": 1,
            "inserted_at": "2022-02-03T20:58:38.000000Z",
            "number_id": 1,
            "updated_at": "2022-02-03T20:58:38.000000Z",
            "uuid": "f6c4e666-81ad-430e-aea5-1ba33e6f4c35"
        },
        ...
    ],
    "paging": {
        "expires_at": "2021-08-30T18:49:26.761537Z",
        "next": "<next cursor>"
    }
}

Se houver mais dados na próxima página, será fornecido um cursor next para continuar obtendo resultados. Caso contrário, significa que todos os resultados para os critérios de pesquisa fornecidos foram alcançados.

Exportar Dados de Status de Mensagens​

Criar um cursor para status de mensagens​

Para criar um cursor para começar a buscar status de mensagens, faça a seguinte solicitação:

$ curl -X POST "https://whatsapp.turn.io/v1/data/statuses/cursor" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -H "accept: application/vnd.v1+json" \
  -d '
    {
        "from": "2021-08-02T01:55:00.272Z",
        "until": "2021-08-20T01:55:00.272Z",
        "ordering": "desc",
        "page_size": 10
    }'
> {
    "cursor": "<cursor>",
    "expires_at": "2021-08-30T17:47:18.318218Z"
}

Obter Status de Mensagens​

O payload de status é estruturado conforme recebido da API Cloud. Isso significa que cada status individual tem a mesma estrutura que seria encaminhada para um webhook que recebe atualizações.

Para obter o status, depois de criar seu cursor, faça a seguinte solicitação:

$ curl -X GET "https://whatsapp.turn.io/v1/data/statuses/cursor/<cursor>" \
    -H 'Authorization: Bearer token' \
    -H "Accept: application/vnd.v1+json" \
> {
  "data": [
    {
      "statuses": [
        {
          "conversation": {
            "id": "51cbaq7cccb833f28931358fce32e2e9",
            "origin": {
              "type": "service"
            }
          },
          "id": "wamid.Kn3rwvPdIVrT0AuGhicCs99I08nVpcz2fbQlFaXyFUdYKdyQUvFY",
          "pricing": {
            "billable": true,
            "category": "service",
            "pricing_model": "CBP"
          },
          "recipient_id": "27123456789",
          "status": "delivered",
          "timestamp": 1727849284
        }
      ]
    },
    {
      "statuses": [
        {
          "errors": [
            {
              "code": 131053,
              "error_data": {
                "details": "Unsupported Video mime type image/jpeg. Please use one of video/3gpp, video/mp4."
              },
              "message": "Media upload error",
              "title": "Media upload error"
            }
          ],
          "id": "wamid.HpXNjw1u8XuqA9FocBjWPTHKh1UzyjifPhezyBhvC7ewPmNZD7GL==",
          "recipient_id": "27123456789",
          "status": "failed",
          "timestamp": 1724284299
        }
      ]
    },
    {
      "statuses": [
        {
          "id": "wamid.HzgKORVuA2NzewdveXA84WphzsZr3qTg29QQXltRFnjjVIB4OCyn",
          "recipient_id": "44123456789",
          "status": "read",
          "timestamp": 1727849706
        }
      ]
    },
    ...
  ],
  "paging": {
      "expires_at": "2021-08-30T18:49:26.761537Z",
      "next": "<next cursor>"
  }
}