Lista de contactos¶

Las listas de contactos permiten almacenar un conjunto de contactos que comparten alguna característica.

Los datos son dinámicos y el cliente puede guardar cualquier campo asociado a los contactos. Es obligatorio incluir al menos un campo para teléfono o un campo para email.

A continuación, se describen los endpoints relacionados con las listas de contactos.

Antes de comenzar¶

Obtenga el token Bearer utilizado por esta API. Para actualizar datos, conserve el identificador de lista UUID-cl; para un contacto individual, conserve también UUID-contact.

Prepare los datos CSV/XLSX con al menos una columna de teléfono o correo. Asigne a cada columna su tipo y mapeo; los nombres de los ejemplos no son campos universales para todas las listas.

Elegir una operación¶

Tarea	Método y ruta relativa
Crear una lista desde archivo	`POST /contact-list/upload`
Cargar datos en una lista existente	`PUT /contact-list/{UUID-cl}/upload`
Listar o recuperar listas	`GET /contact-list` o `GET /contact-list/{UUID-cl}`
Actualizar nombre o descripción	`PUT /contact-list/{UUID-cl}`
Consultar o agregar contactos	`GET` o `POST /contact-list/{UUID-cl}/contact`
Actualizar o eliminar un contacto	`PATCH` o `DELETE /contact-list/{UUID-cl}/contact/{UUID-contact}`
Eliminar una lista	`DELETE /contact-list/{UUID-cl}`

Utilice la URL completa indicada en cada sección. Eliminar un contacto y eliminar una lista completa son operaciones distintas.

Lista de contacto¶

Crear lista de contacto desde un archivo¶

POST https://api.obmessage.ai/api/v1/contact-list/upload
Authorization: Bearer {{JWT_TOKEN}}

{
    "params": {
        "skip_row_with_error": true
    },
    "info": {
        "name": "string",
        "description": "string",
        "has_header": true,
        "sheet": "string",
        "encoding": "string",
        "config": {
            "columns": [
                {
                    "index": 0,
                    "source_name": "string",
                    "target_name": "string",
                    "display_name": "string",
                    "order": 1,
                    "type": "string"
                }
            ]
        }
    }
}

Este endpoint lee archivos .csv o .xlsx en formato de columnas de 0 a n.

Por ejemplo, se puede crear una lista de contacto llamada datos de prueba utilizando la primera columna del archivo filename.csv, y asignar a dicha columna el nombre name.

La tabla siguiente describe los metadatos de la lista. Campos como name, has_header y config pertenecen al objeto info, como muestra la estructura JSON; params es un objeto separado.

Campo	Descripción	Obligatorio
params	Parámetros adicionales de la carga.	No
params.skip_row_with_error	Indica si se deben omitir filas con errores durante la carga de la lista de contactos.	No
name	Nombre de la lista de contacto.	No
description	Descripción de la lista de contacto.	No
has_header	Indica si los datos del archivo poseen una fila de encabezados.	Sí
sheet	Hoja que se procesará en archivos `.xlsx`.	No
encoding	Encoding del archivo. Solo aplica para `.csv`.	No
config	Configuración de las columnas que posee la lista de contacto.	Sí
config.columns.id	Código de identificación de la columna en la lista de contacto.	Sí
config.columns.index	Índice de la columna en el archivo, de `0` a `n`. Si la lista tiene más de una columna, este campo es requerido.	Sí
config.columns.type	Tipo de dato de la columna. Ver Tipos de datos.	Sí
config.columns.order	Orden o prioridad de la columna. Si la lista tiene más de una columna, este campo es requerido.	Sí
config.columns.source_name	Nombre de la columna cuando el archivo posee encabezados.	No
config.columns.target_name	Nombre asignado a la columna.	Sí
config.columns.display_name	Nombre amigable de la columna.	No

Tipos de datos¶

A continuación, se describen los tipos de datos soportados:

Tipo de dato	Descripción
text	Cadena de longitud variable de letras, números y caracteres especiales. Longitud máxima: 255.
integer	Número entero con signo.
decimal	Número decimal de punto fijo con precisión `(18, 2)`.
phone	Número telefónico compatible con la recomendación E.164.
email	Correo electrónico.
date	Fecha en formato `YYYY-MM-DD`.
time	Hora en formato `HH:mm:ss`.
datetime	Fecha y hora en formato `YYYY-MM-DD HH:mm:ss`.

Nota

Todos los tipos de datos son validados de acuerdo con estas especificaciones al momento de crear o actualizar la lista de contacto.

Pruébalo en Postman

Actualizar los datos de una lista de contacto desde un archivo¶

PUT https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}/upload
Authorization: Bearer {{JWT_TOKEN}}

{
    "params": {
        "append": true,
        "skip_row_with_error": true
    }
}

UUID-cl: ID de la lista de contacto.

Pruébalo en Postman

Este endpoint actualiza los datos de una lista de contacto desde un archivo.

Parámetro de carga	Descripción
params.append	Indica si se debe realizar un append a la lista de contactos. Para más información sobre append, puede consultar este enlace.
params.skip_row_with_error	Indica si se deben omitir filas con errores durante la carga de la lista de contactos.

Consultar listas de contactos¶

GET https://api.obmessage.ai/api/v1/contact-list
Authorization: Bearer {{JWT_TOKEN}}

Este endpoint permite visualizar las listas de contactos existentes. El resultado se entrega como una paginación de listas de contactos.

Este endpoint soporta los siguientes parámetros o filtros:

Campo	Descripción
id	Código de identificación de la lista de contacto.
name	Nombre de la lista de contacto.
current_page	Página que se desea obtener.
items_per_page	Cantidad máxima de elementos por página.
desc	Orden de paginación de los datos. Por defecto es `asc`.

Respuesta de ejemplo: 200 OK

{
    "current_page": 1,
    "items_per_page": 5,
    "items": [
        {
            "id": "ece619cb-605e-4150-be72-3f3b920e0bd7",
            "name": "test",
            "description": "test",
            "has_header": true,
            "encoding": "",
            "sheet": "",
            "created_at": "2022-10-31T14:33:17.434Z"
        }
    ]
}

Pruébalo en Postman

Consultar una lista de contacto por ID¶

GET https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}
Authorization: Bearer {{JWT_TOKEN}}

UUID-cl: ID de la lista de contacto.

Respuesta de ejemplo: 200 OK

{
    "id": "73143085-198c-4538-941b-45517077de67",
    "name": "test",
    "description": "test",
    "has_header": true,
    "encoding": "",
    "sheet": "",
    "created_at": "2022-10-31T14:33:17.434Z",
    "updated_at": "2022-10-31T15:38:43.765Z",
    "config": {
        "columns": [
            {
                "id": "14af0d04-715b-432e-9550-a5736acf468c",
                "index": 0,
                "type": "text",
                "order": 1,
                "source_name": "test",
                "target_name": "test",
                "display_name": "test"
            }
        ]
    }
}

Actualizar una lista de contacto¶

PUT https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/json

UUID-cl: ID de la lista de contacto.

Pruébalo en Postman

Este endpoint actualiza una lista de contacto por su ID.

Solo se pueden actualizar los siguientes campos:

name
description

Nota

Retorna la lista de contacto en formato JSON.

Eliminar una lista de contacto¶

DELETE https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}
Authorization: Bearer {{JWT_TOKEN}}

Pruébalo en Postman

Elimina una lista de contacto por su ID.

Contacto¶

Consultar contactos de una lista¶

GET https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}/contact
Authorization: Bearer {{JWT_TOKEN}}

Pruébalo en Postman

UUID-cl: ID de la lista de contacto.

Este endpoint permite visualizar los datos de una lista de contacto determinada. El resultado se entrega como una paginación de contactos cuya data es dinámica.

Este endpoint soporta los siguientes parámetros o filtros:

Campo	Descripción
pk_id	Código de identificación del contacto.
current_page	Página que se desea obtener.
items_per_page	Cantidad máxima de elementos por página.
desc	Orden de paginación de los datos. Por defecto es `asc`.

Respuesta de ejemplo: 200 OK

{
    "current_page": 1,
    "items_per_page": 10,
    "items": [
        {
            "contact_id": "71088a9d-7aa3-4736-8e17-383a4a567b9b",
            "id": 1,
            "nombre": "juan perez",
            "telefono": "+18099999999",
            "email": "test@test.com",
            "columna1": "1",
            "columna2": "2"
        }
    ]
}

Consultar un contacto por ID¶

GET https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}/contact/{UUID-contact}
Authorization: Bearer {{JWT_TOKEN}}

Pruébalo en Postman

Este endpoint obtiene un contacto determinado por su ID.

Campo	Descripción
UUID-cl	ID de la lista de contacto.
UUID-contact	ID del contacto.

Respuesta de ejemplo: 200 OK

{
    "contact_id": "71088a9d-7aa3-4736-8e17-383a4a567b9b",
    "id": 1,
    "nombre": "juan perez",
    "telefono": "+18099999999",
    "email": "test@correo.com",
    "columna1": "1",
    "columna2": "2"
}

Agregar un nuevo contacto¶

POST https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}/contact
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/json

Pruébalo en Postman

Este endpoint agrega un nuevo contacto a una lista de contacto determinada.

Campo	Descripción
UUID-cl	ID de la lista de contacto.

Recibe una trama en formato JSON con los datos del nuevo contacto. Por ejemplo:

{
    "name": "juan perez",
    "tel": "+18099999999"
}

Actualizar parcialmente un contacto¶

PATCH https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}/contact/{UUID-contact}
Authorization: Bearer {{JWT_TOKEN}}
Content-Type: application/json

Pruébalo en Postman

Actualiza parcialmente un contacto de una lista de contacto determinada.

Campo	Descripción
UUID-cl	ID de la lista de contacto.
UUID-contact	ID del contacto.

Por ejemplo:

{
    "name": "Juan Perez",
    "phone": "+18099999999"
}

Eliminar un contacto¶

DELETE https://api.obmessage.ai/api/v1/contact-list/{UUID-cl}/contact/{UUID-contact}
Authorization: Bearer {{JWT_TOKEN}}

Pruébalo en Postman

Elimina un contacto de una lista de contacto determinada.

Campo	Descripción
UUID-cl	ID de la lista de contacto.
UUID-contact	ID del contacto.

Comprobar el resultado¶

Después de crear o actualizar una lista, consúltela por ID y revise sus contactos. Compare las columnas y los valores con los datos de origen. Si permite omitir errores en una carga, revise el historial de carga antes de utilizar la audiencia.

El JSON de carga describe metadatos, no el archivo CSV/XLSX en sí. Utilice la configuración de carga suministrada para su integración; si no conoce el formato de adjuntar el archivo, solicítelo a soporte antes de implementar la petición.