Recuperar contactos

Aquí encontrarás cómo recuperar la información de uno o varios contactos según la búsqueda por ciertos criterios.

El servicio para exportar contactos permite realizar una búsqueda en la base de datos de contacto según los criterios enviados, la respuesta exitosa que recibirás de parte del API será un arreglo de contactos con todas sus propiedades (campos estándar, campos personalizados y tags), para realizar búsqueda más especificas puedes utilizar los filtros y mejorar la búsqueda.

Los filtros disponibles en el API son:

Recuperar Contactos

GET https://api.b2chat.io/contacts/export

Este método te permitirá traer los datos de un contacto en especifico, o un arreglo de contactos que coincidan con unos filtros aplicados

Headers

NameTypeDescription

Content-Type*

application/json

Authorization*

Bearer {{token}}

Request Body

NameTypeDescription

limit*

100

Limitado a un número máximo de 1k de registros para devolver

offset*

10

Número de registros que se deben omitir antes de recuperar un resultado. Permite paginación.

created

{"from": "2020-01-01", "to": "2020-12-31"}

Rango de fecha del cual se quieren extraer los contactos, basado en la fecha de creación del contacto. Formato: {"from": "2020-01-01", "to": "2020-12-31"}

updated

{"from": "2020-01-01", "to": "2020-12-31"}

Rango de fecha del cual se quieren extraer los contactos basado en la ultima fecha de actualización del contacto. Formato: {"from": "2020-01-01", "to": "2020-12-31"}

order_dir

ASC

Aplica solo si se aplican filtros por fecha de creación o actualización, los valores son ASC o DESC.

skip_custom_attributes

TRUE

Este campo permite mostrar o no los campos personalizados de los contactos, al colocar el campo en TRUE, no se mostrará en la respuesta los campos personalizados al colocarse en FALSE se mostraran los campos personalizados en la respuesta.

Si la propiedad no se incluye en el request, por defecto esta en TRUE.

skip_tags

TRUE

Este campo permite mostrar o no los tags aplicados a los contactos, al colocar el campo en TRUE, no se mostrará en la respuesta los tags aplicados, al colocarse en FALSE se mostraran los tags asignados en la respuesta. Si este campo no tiene ningun valor, por defecto esta en TRUE.

contact_lookup

String

Este campo es un filtro que permite buscar por ciertos campos de los contactos para buscar un contacto en especifico, los campos se pueden combinar en la búsqueda, estos campos son:

id: Puedes realizar las búsquedas por id del contacto.

name: Puedes realizar las búsquedas por el nombre del contacto, la búsqueda se realiza sin diferencias mayúsculas o minúsculas.

mobile: Puedes realizar búsquedas por coincidencia completa del número móvil o coincidencia parcial de los últimos 7 números del móvil del contacto.

email: Puedes realizar búsquedas por coincidencia completa del email

#200
{
    "total": 22197,
    "exported": 3,
    "contacts": [
        {
            "contact_id": 123456789,
            "fullname": "John Doe",
            "identification": "123456789",
            "email": "jhon@b2chat.io",
            "landline": "",
            "mobile": "+57123456789",
            "address": "5th avenue north",
            "country": "CO",
            "city": "Medellin",
            "company": "B2CHAT",
            "merchant_id": null,
            "created": "2020-11-09 19:10:23",
            "updated": "2024-01-25 16:24:14",
            "custom_attributes": [
                {
                    "attribute_name": "Asesor",
                    "attribute_value": null
                },
                {
                    "attribute_name": "Observación",
                    "attribute_value": "ss"
                },
                {
                    "attribute_name": "Referido por",
                    "attribute_value": null
                }
            ]
        },
        {
            "contact_id": 456789123,
            "fullname": "Jaime R",
            "identification": "",
            "email": "",
            "landline": "",
            "mobile": "",
            "address": "",
            "country": null,
            "city": "",
            "company": "",
            "merchant_id": null,
            "created": "2020-12-23 21:12:54",
            "updated": "2022-05-19 21:56:59",
            "custom_attributes": [
                {
                    "attribute_name": "Asesor",
                    "attribute_value": null
                },
                {
                    "attribute_name": "Observación",
                    "attribute_value": "VV"
                },
                {
                    "attribute_name": "Referido por",
                    "attribute_value": null
                }
            ],
            "tags": []
        },
        {
            "contact_id": 789456123,
            "fullname": "Peter P",
            "identification": "",
            "email": "",
            "landline": "",
            "mobile": "+571245789874",
            "address": "",
            "country": null,
            "city": "",
            "company": "",
            "merchant_id": null,
            "created": "2022-03-29 19:10:52",
            "updated": "2022-03-29 19:10:52",
            "custom_attributes": [
                {
                    "attribute_name": "Asesor",
                    "attribute_value": null
                },
                {
                    "attribute_name": "Observación",
                    "attribute_value": "AA"
                },
                {
                    "attribute_name": "Referido por",
                    "attribute_value": null
                }
            ],
            "tags": [
                {
                    "name": "Tag1",
                    "assigned_at": 1706644084
                },
                {
                    "name": "Tag2",
                    "assigned_at": 1706648261
                },
                {
                    "name": "Tag3",
                    "assigned_at": 1706644082
                }
            ]
```
        }
    ],
    "trace_id": "409e27e3-506b-444f-b3f3-7ad80d295182",
    "message": "3 contacts were exported"
}

En caso de que necesite enviar parámetros query string en lugar de datos JSON , use los mismos parámetros excepto la fecha created que recibirá en su lugar dos parámetros created_from y created_to y excepto la fecha updated que recibirá en su lugar dos parámetros updated_from y updated_to.

Paginación para exportar mas de 1000 Contactos:

Dado que cada solicitud al API tiene un límite de 1000 registros por respuesta, existe un mecanismo de paginación para acceder a un mayor número de registros. Esto se logra mediante dos parámetros: offset y total, incluidos en el request y respuesta del servicio.

Por ejemplo: Si desea exportar 5000 contactos desde B2Chat a través del API, comience realizando una solicitud inicial con order_dir establecido en DESC y limit en 1000. Esta acción le proporcionará los primeros 1000 contactos.

En la respuesta, encontrará un campo llamado Total, que indica el número total de registros disponibles, que en este caso serían 5000. Divida este total por el límite máximo de registros por página para determinar el número total de solicitudes necesarias para recuperar todos los datos.

Sabiendo ya que necesita realizar 5 consultas, para las siguientes solicitudes, ajuste el parámetro offset al número del registro que inicia la siguiente página, en este caso, 1001. De esta manera, podrá recuperar todos los registros en 5 llamadas, cada una solicitando 1000 registros.

  • Ejemplo 1: Trae hasta 999 contactos y la respuesta no incluira los campos personalizados solo los estándar. Como no se especifica rango de fecha se entregan los registros ordenados por fecha de creación en orden DESC (Trae los últimos 999 contactos creados)

curl --location --request GET 'https://api.b2chat.io/contacts/export' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
  "filters": {
    "limit": 999,
    "skip_custom_attributes": true
	}
}'

  • Ejemplo 2: Trae 500 contactos en orden ASC (Trae los primeros 500 contactos creados) se toa la fecha de creación por defecto ya que no se uso filtro por rango ni de creación ni de actualización.

curl --location --request GET 'https://api.b2chat.io/contacts/export' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
	"filters": {
		"limit": 500,
	  	"order_dir": "asc"
  }
}'

  • Ejemplo 3: Trae 120 Contactos partiendo del registro 100.

curl --location --request GET 'https://api.b2chat.io/contacts/export' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
	"filters":{
		"limit": 120,
	  	"offset": 100
	}
}'

  • Ejemplo 4: Llamado para recuperar un contacto mas especifico filtando con contact_lookup por id, nombre, mobile ó email, adicionalmente se incluye un filtro de rango de fecha de actualización, y se ponen en falso los parámetros para ignorar campos personalizados y tags, dando como resultado una respuesta de contactos con sus campos personalizados y tags asociados.

curl --location --request GET 'https://api.b2chat.io/contacts/export' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{token}}' \
--data '{
"filters": {
        "limit": 10,
        "offset": 1,
        "update": {"from": "2024-01-01", "to": "2024-01-26"},
        "order_dir": "asc",
        "skip_custom_attributes": false,
        "skip_tags": false,
        "contact_lookup": [
            {
                "field": "id|name|mobile|email",
                "value":"VALUE"
            }
        ]
    }
}'

  • Otro ejemplo de llamado usando query params

curl --location --request GET 'https://api.b2chat.io/contacts/export?limit=999&offset=0&updated_from=2019-12-01&updated_to=2019-12-31&order_dir=asc' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}'

PreviousContactosNextCrear Contactos

Last updated