Referencia de la API de contactos
Busca, lee y actualiza contactos de Chatfuel: atributos, nombres, notas, responsables y etapas de venta, segmentos, importación y exportación CSV y eventos.
Última actualización
Un contacto es una persona que habló con el bot en WhatsApp, Instagram, Facebook, TikTok o el widget del sitio web. Con la Public API puedes buscar contactos con segmentos, leer sus atributos, cambiar nombres, atributos y notas, asignarlos a compañeros de equipo o a Fuely AI, moverlos entre etapas de venta e importarlos o exportarlos como CSV. Leer contactos funciona para usuarios virtuales Agent; editar los datos de un contacto requiere Editor.
A los contactos se accede a través de bot(id:). El ID de un contacto también es el ID de su conversación, como se describe en mensajería.
Cómo buscar y leer contactos
type Bot {
# Agent. One contact by ID.
contact(id: ContactID!): Contact!
# Agent. Paginated search, up to 500 per page, optionally filtered by a segment and sorted by an attribute.
contactsConnection(
platforms: [Platform!]! # whatsapp, instagram, facebook, tiktok, widget
first: Int!
before: ContactSearchCursor
after: ContactSearchCursor
segment: SegmentInput
orderBy: ContactSearchOrderByInput # { orderBy: <attribute name>, direction: Asc | Desc }
): ContactConnection!
# Agent. Number of contacts matching the platforms and segment.
contactsCount(platforms: [Platform!]!, segment: SegmentInput): Int!
contactsTotalCount(platforms: [Platform!]!, segment: SegmentInput): Int!
}Contact es una interfaz; los contactos de WhatsApp son WhatsappContact, con un campo phone adicional, y hay tipos similares para los demás canales. Todo contacto tiene:
query Contact($botID: BotID!, $contactID: ContactID!) {
bot(id: $botID) {
contact(id: $contactID) {
id
name
note
updatedAt
salesStageV2 # New, Sorting, Ready, WorkingOn, Won, Lost
lastConversationMessageTime
unreadMessagesCount
unhandledSwitchToHuman # handed to a human and not opened yet
assignee {
... on PublicUserAccount { id name accountType }
... on FuelyAIAssignee { __typename }
}
attributes(names: ["email", "city"]) {
attr { name type }
value {
... on BotAttributeValueString { stringValue }
... on BotAttributeValueDouble { doubleValue }
... on BotAttributeValueBoolean { booleanValue }
... on BotAttributeValueDatetime { datetimeValue }
}
}
... on WhatsappContact { phone }
}
}
}Cómo filtrar contactos con segmentos
Un segmento es un conjunto de filtros unidos con AND u OR. Los IDs de segmentos y filtros son UUID que tú generas; también puedes llamar a segmentNew para obtener un segmento vacío con un ID:
query Leads($botID: BotID!) {
bot(id: $botID) {
contactsConnection(
platforms: [whatsapp]
first: 100
segment: {
id: "2b0c6a0e-6f0a-4a39-9d63-0b1f0d4f7a10"
resultOperator: AND
filters: [{
id: "8f6d2a4e-1c3b-4f5a-9e7d-2a1b3c4d5e6f"
byAttribute: { name: "city", defaultStrategy: { operator: IS, comparableValues: ["Lisbon"] } }
}]
}
) {
edges { node { id name } }
pageInfo { hasNextPage endCursor }
}
}
}Los filtros por atributo admiten los operadores IS, IS_NOT, STARTS_WITH, CONTAINS, LT, GT, IS_EMPTY e IS_NOT_EMPTY; los atributos de fecha usan dateStrategy. bot.botAttributes(...) lista los atributos del sistema y personalizados de un bot, con sus tipos de datos (Agent).
Cómo actualizar un contacto
type Mutation {
# Editor. Errors: ContactDoesNotExist, ContactNameTooLong, ContactNameRequired
contactUpdateName(id: ContactID!, name: String!): Contact!
# Editor. Creates or updates a custom attribute. System attributes can't be changed (SystemAttributeUpdateNotAllowed).
contactAttributeUpdate(id: ContactID!, attrName: AttributeName!, attrValue: String!): Contact!
# Editor. Deletes a custom attribute value from the contact.
contactAttributeDelete(id: ContactID!, attrName: AttributeName!): Contact!
# Editor. A free-text note shown on the contact card and in bookings. Errors: ContactNoteTooLong
contactSetNote(id: ContactID!, note: String): Contact!
# Agent. The person must have access to the bot's contacts (AssigneeHasNoAccess).
contactSetAssignee(id: ContactID!, assigneeID: UserAccountID!): Contact!
# Agent. Hands the contact to Fuely AI.
contactSetFuelyAIAssignee(id: ContactID!): Contact!
# Agent.
contactRemoveAssignee(id: ContactID!): Contact!
# Agent. Moves the contact on the Leads board.
contactSetSalesStage(id: ContactID!, salesStageV2: SalesStageV2!): Contact!
# Editor. Creates a WhatsApp contact by phone number for a calendar booking (source: CalendarBooking).
whatsappContactCreateV2(botID: BotID!, data: WhatsappContactCreateInput!): Contact!
}Un usuario virtual puede asignarse un contacto a sí mismo: pasa su propio currentUser.id como assigneeID.
Los valores predeterminados de los atributos del bot se aplican a todo contacto que no tenga un valor propio (Editor):
type Mutation {
botAttributeCreateDefaultVal(botID: BotID!, attributeName: AttributeName!, defaultValue: String!): Bot!
botAttributeUpdateDefaultVal(botID: BotID!, attributeName: AttributeName!, defaultValue: String!): Bot!
botAttributeDeleteDefaultVal(botID: BotID!, attributeName: AttributeName!): Bot!
}Cómo leer negocios por etapa de venta
El tablero de Leads agrupa los contactos por etapa de venta. Ambas consultas funcionan para Agent:
type Bot {
# Contacts in one stage, filtered by assignee (Any, Unassigned, FuelyAI or a specific AssigneeID).
contactDealsConnection(
first: Int!
before: ContactSearchCursor
after: ContactSearchCursor
assigneeFilter: ContactAssigneeFilter!
salesStageV2Filter: SalesStageV2!
): ContactConnection!
# Number of contacts in each stage, optionally limited by the time of the last stage change.
contactDealsByStages(filter: DealsByStagesFilter!): TotalsByStages!
}Cómo exportar e importar contactos como CSV
Las exportaciones e importaciones se ejecutan en segundo plano e informan su progreso mediante una tarea o una suscripción.
type Mutation {
# Agent. Export by segment; pass an empty attributes list to export all attributes.
# Errors: CSVContactExportAlreadyInProgress
csvContactExportStartBySegment(botID: BotID!, platforms: [Platform!]!, segment: SegmentInput, attributes: [AttributeName!]!): Task!
# Agent. Export a list of contacts. Errors: CSVContactExportInvalidContactIDsCount
csvContactExportStartByIDsList(botID: BotID!, contactIDs: [ContactID!]!, attributes: [AttributeName!]!): Task!
# Agent. Cancels an export; the task status changes to cancelled shortly after.
csvContactExportCancel(botID: BotID!, id: String!): Bot!
# Editor. 1) upload the CSV file, 2) create the import, 3) map columns, 4) start it.
csvContactImportCreate(botID: BotID!, fileID: FileID!, platform: Platform!, locale: DashboardLocale!): CSVContactImport!
csvContactImportUpdateFile(botID: BotID!, id: CSVContactImportID!, fileID: FileID!): CSVContactImport!
csvContactImportUpdateColumns(botID: BotID!, id: CSVContactImportID!, request: CSVContactImportColumnsUpdate!): CSVContactImport!
# Errors: ContactScopeNotConnected if the channel, for example the WhatsApp number, is not connected.
csvContactImportStart(botID: BotID!, id: CSVContactImportID!): CSVContactImport!
}Cuando una tarea de exportación llega al estado Finished, su data es un CSVContactsExport cuyo file { url } es el CSV que debes descargar. bot.lastActiveCSVContactsExportTask (Agent) devuelve una exportación en curso, y bot.latestCSVContactsImport(platform:) (Editor), la última importación con sus contadores y errores.
Suscripciones de contactos
type Subscription {
# Agent. Any change of one contact.
contactUpdated(botID: BotID!, contactID: ContactID!): Contact
# Agent. Changes on the Leads board for the given assignee filter.
contactsDealUpdates(botID: BotID!, assigneeFilter: ContactAssigneeFilter!): ContactsDealUpdate
contactsDealsPageIndicatorUpdates(botID: BotID!): DealsPageIndicatorUpdate
# Editor. Progress of a CSV import.
csvContactImportUpdated(botID: BotID!, id: CSVContactImportID!): CSVContactImport!
}Problemas comunes
"NotEnoughPermissions" cuando un Agent edita un contacto
Los Agents pueden asignar contactos y cambiar etapas de venta, pero cambiar nombres, atributos y notas requiere un Editor. Si un Editor también recibe este error, puede que la configuración de roles del bot lo limite a los contactos asignados a él, como se describe en equipo y roles.
"SystemAttributeUpdateNotAllowed"
Chatfuel define los atributos del sistema, como el número de teléfono o los datos de perfil del canal. Guarda tus propios datos en atributos personalizados.
"ContactDoesNotExist"
El ID del contacto es incorrecto o pertenece a otro bot. Los IDs de contacto son específicos de cada bot; léelos de contactsConnection del mismo bot.
Referencia de la API de equipo y roles
Lista miembros e invitaciones, y crea, rota, cambia de rol o elimina usuarios virtuales. Cambiar el equipo requiere el token de API personal de un Admin.
Referencia de la API de mensajería
Lee conversaciones y envía texto, archivos y plantillas de WhatsApp en WhatsApp, Instagram, Facebook, TikTok y el widget del sitio web con la Public API.