Создайте телефонные поля для хранения и проверки номеров телефонов с международным форматом
Пользовательские телефонные поля позволяют вам хранить номера телефонов в записях с встроенной проверкой и международным форматом. Они идеально подходят для отслеживания контактной информации, экстренных контактов или любых данных, связанных с телефоном, в ваших проектах.
Простой пример
Создайте простое телефонное поле:
mutation CreatePhoneField {
createCustomField(input: {
name: "Contact Phone"
type: PHONE
}) {
id
name
type
}
}
Расширенный пример
Создайте телефонное поле с описанием:
mutation CreateDetailedPhoneField {
createCustomField(input: {
name: "Emergency Contact"
type: PHONE
description: "Emergency contact number with country code"
}) {
id
name
type
description
}
}
Входные параметры
CreateCustomFieldInput
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
name |
String! | ✅ Да | Отображаемое имя телефонного поля |
type |
CustomFieldType! | ✅ Да | Должен быть PHONE |
description |
String | Нет | Текст помощи, отображаемый пользователям |
Примечание: Пользовательские поля автоматически ассоциируются с проектом на основе текущего контекста проекта пользователя. Параметр projectId не требуется.
Установка значений телефона
Чтобы установить или обновить значение телефона в записи:
mutation SetPhoneValue {
setTodoCustomField(input: {
todoId: "todo_123"
customFieldId: "field_456"
text: "+1 234 567 8900"
})
}
SetTodoCustomFieldInput Параметры
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
todoId |
String! | ✅ Да | ID записи для обновления |
customFieldId |
String! | ✅ Да | ID пользовательского телефонного поля |
text |
String | Нет | Номер телефона с кодом страны |
regionCode |
String | Нет | Код страны (автоматически определяется) |
Примечание: Хотя text является необязательным в схеме, номер телефона требуется, чтобы поле имело смысл. При использовании setTodoCustomField никакая проверка не выполняется - вы можете хранить любое текстовое значение и regionCode. Автоматическое определение происходит только при создании записи.
Создание записей с телефонными значениями
При создании новой записи с телефонными значениями:
mutation CreateRecordWithPhone {
createTodo(input: {
title: "Call client"
todoListId: "list_123"
customFields: [{
customFieldId: "phone_field_id"
value: "+1-555-123-4567"
}]
}) {
id
title
customFields {
id
customField {
name
type
}
text
regionCode
}
}
}
Поля ответа
TodoCustomField Ответ
| Поле | Тип | Описание |
|---|---|---|
id |
String! | Уникальный идентификатор для значения поля |
customField |
CustomField! | Определение пользовательского поля |
text |
String | Отформатированный номер телефона (международный формат) |
regionCode |
String | Код страны (например, "US", "GB", "CA") |
todo |
Todo! | Запись, к которой принадлежит это значение |
createdAt |
DateTime! | Когда значение было создано |
updatedAt |
DateTime! | Когда значение было в последний раз изменено |
Проверка номера телефона
Важно: Проверка и форматирование номера телефона происходит только при создании новых записей через createTodo. При обновлении существующих телефонных значений с использованием setTodoCustomField никакая проверка не выполняется, и значения хранятся как указано.
Допустимые форматы (при создании записи)
Номера телефонов должны включать код страны в одном из следующих форматов:
- Формат E.164 (предпочтительный):
+12345678900 - Международный формат:
+1 234 567 8900 - Международный с пунктуацией:
+1 (234) 567-8900 - Код страны с дефисами:
+1-234-567-8900
Примечание: Национальные форматы без кода страны (например, (234) 567-8900) будут отклонены при создании записи.
Правила проверки (при создании записи)
- Использует libphonenumber-js для разбора и проверки
- Принимает различные международные форматы номеров телефонов
- Автоматически определяет страну по номеру
- Форматирует номер в международном формате отображения (например,
+1 234 567 8900) - Извлекает и хранит код страны отдельно (например,
US)
Примеры действительных телефонов
+12345678900 # E.164 format
+1 234 567 8900 # International format
+1 (234) 567-8900 # With parentheses
+1-234-567-8900 # With dashes
+44 20 7946 0958 # UK number
+33 1 42 86 83 26 # French number
Примеры недействительных телефонов
(234) 567-8900 # Missing country code
234-567-8900 # Missing country code
123 # Too short
invalid-phone # Not a number
+1 234 # Incomplete number
Формат хранения
При создании записей с номерами телефонов:
- text: Хранится в международном формате (например,
+1 234 567 8900) после проверки - regionCode: Хранится как ISO код страны (например,
US,GB,CA) автоматически определенный
При обновлении через setTodoCustomField:
- text: Хранится точно так, как указано (без форматирования)
- regionCode: Хранится точно так, как указано (без проверки)
Необходимые разрешения
| Действие | Необходимое разрешение |
|---|---|
| Create phone field | OWNER or ADMIN role at project level |
| Update phone field | OWNER or ADMIN role at project level |
| Set phone value | Standard record edit permissions |
| View phone value | Standard record view permissions |
Ответы об ошибках
Неверный формат телефона
{
"errors": [{
"message": "Invalid phone number format.",
"extensions": {
"code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
}
}]
}
Поле не найдено
{
"errors": [{
"message": "Custom field not found",
"extensions": {
"code": "CUSTOM_FIELD_NOT_FOUND"
}
}]
}
Отсутствует код страны
{
"errors": [{
"message": "Invalid phone number format.",
"extensions": {
"code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
}
}]
}
Рекомендации по лучшим практикам
Ввод данных
- Всегда включайте код страны в номера телефонов
- Используйте формат E.164 для согласованности
- Проверяйте номера перед хранением для важных операций
- Учитывайте региональные предпочтения для формата отображения
Качество данных
- Храните номера в международном формате для глобальной совместимости
- Используйте regionCode для функций, специфичных для страны
- Проверяйте номера телефонов перед критическими операциями (SMS, звонки)
- Учитывайте временные зоны для времени контактов
Международные соображения
- Код страны автоматически определяется и хранится
- Номера форматируются в международном стандарте
- Региональные предпочтения отображения могут использовать regionCode
- Учитывайте местные правила набора при отображении
Общие случаи использования
-
Управление контактами
- Номера телефонов клиентов
- Контактная информация поставщиков
- Номера телефонов членов команды
- Контактные данные поддержки
-
Экстренные контакты
- Номера экстренных контактов
- Контактная информация дежурного
- Контакты для реагирования на кризисы
- Номера телефонов для эскалации
-
Поддержка клиентов
- Номера телефонов клиентов
- Номера обратной связи поддержки
- Номера для проверки
- Номера для последующих контактов
-
Продажи и маркетинг
- Номера телефонов лидов
- Списки контактов для кампаний
- Контактная информация партнеров
- Номера телефонов источников рекомендаций
Функции интеграции
С автоматизацией
- Запуск действий при обновлении телефонных полей
- Отправка SMS-уведомлений на сохраненные номера телефонов
- Создание задач для последующих действий на основе изменений телефона
- Направление звонков на основе данных номера телефона
С справочниками
- Ссылка на телефонные данные из других записей
- Сбор телефонных списков из нескольких источников
- Поиск записей по номеру телефона
- Перекрестная ссылка контактной информации
С формами
- Автоматическая проверка телефона
- Проверка международного формата
- Определение кода страны
- Обратная связь по формату в реальном времени
Ограничения
- Требуется код страны для всех номеров
- Нет встроенных возможностей SMS или звонков
- Нет проверки номера телефона, кроме проверки формата
- Нет хранения метаданных телефона (оператор, тип и т.д.)
- Национальные номера без кода страны отклоняются
- Нет автоматического форматирования номера телефона в интерфейсе, кроме международного стандарта
Связанные ресурсы
- Текстовые поля - Для не телефонных текстовых данных
- Поля электронной почты - Для адресов электронной почты
- Поля URL - Для адресов веб-сайтов
- Обзор пользовательских полей - Общие концепции