> ## Documentation Index > Fetch the complete documentation index at: https://docs.connectadesk.com/llms.txt > Use this file to discover all available pages before exploring further. # Atualizar agendamento > Só é possível editar agendamentos que ainda não foram enviados: | Estado | Editável | Resposta | | --- | --- | --- | | `PENDENTE` | sim | Aguardando o horário. | | `ERRO` | sim | O envio falhou. Editar reprograma o envio. | | `AGENDADA` | não | `409 ERR_API_SCHEDULE_NOT_EDITABLE`. O envio já está na fila. | | `ENVIADA` | não | `409 ERR_API_SCHEDULE_ALREADY_SENT` | | `CANCELADA` | não | `409 ERR_API_SCHEDULE_CANCELED`. Crie um novo agendamento. | Se você trocar o canal de um agendamento com template, envie o `template` de novo. Um template aprovado no canal antigo pode não existir no novo. **Mídia:** em canais de WhatsApp não oficial (`web_whatsapp`, `web_whatsapp_premium`), o arquivo pode ser enviado junto, como `multipart/form-data` no campo `file`. Nesses canais o arquivo é a própria mensagem e o `body` vira a legenda. Com anexo, o texto deixa de ser obrigatório. Em canal oficial, o anexo só é aceito quando o template tem cabeçalho de mídia. Caso contrário, a resposta é `400 ERR_API_TEMPLATE_MEDIA_NOT_ALLOWED`, porque a Meta não aceita anexo avulso. ## OpenAPI ````yaml /api-reference/openapi.yaml put /schedules/{id} openapi: 3.0.3 info: title: Connecta DESK API pública version: 1.0.0 description: > API pública do Connecta DESK, disponível em `/api/v1`. O acesso é feito com um token gerado no módulo de tokens. Cada token tem permissões por **módulo × método**, e toda leitura de lista é paginada. ## Autenticação ``` Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 ``` O token pertence a uma **empresa**, e não a um usuário. A empresa usada é sempre a do token, então enviar `companyId` no corpo não tem efeito. Token ausente, inválido, revogado ou expirado recebe a mesma resposta `401`. ## Ordem de verificação 1. **token** → `401` 2. **empresa ativa** → `403` 3. **API habilitada no plano** → `403 ERR_API_NOT_ENABLED` (não se aplica a on-premise) 4. **rate limit da empresa** → `429` 5. **permissão do token** → `403 ERR_API_FORBIDDEN_SCOPE` ## Ids de usuário Todo id de usuário na API é o id do usuário **nesta empresa**, o mesmo que `GET /users` devolve. Vale para o que a API responde (`user.id`, `assignedTo.id`, `userCreated.id`) e para o que ela aceita (`userId`, `userIds`, `assignedToUserId` e o `{id}` das rotas de usuário). A mesma pessoa pode trabalhar em várias empresas, com nome e perfil diferentes em cada uma, e tem um id diferente em cada empresa. Um id que não pertence a esta empresa responde `404`, com a mesma mensagem de um id inexistente. ## Paginação Todo `GET` de lista é paginado. O `meta` traz apenas `page`, `perPage` e `hasMore`, sem o total de registros. Para percorrer tudo, avance `page` enquanto `hasMore` for `true`. ## Idempotência Opcional em `POST`/`PUT`, pelo header `Idempotency-Key`. Se você repetir a chamada com a mesma chave e o mesmo corpo, recebe a resposta já gravada (com `Idempotent-Replay: true`). Com a mesma chave e um corpo diferente, a resposta é `409`. servers: - url: https://api.connectadesk.com/api/v1 description: Produção security: - apiToken: [] tags: - name: contacts description: Cadastro de contatos, campos extras e origem de marketing. - name: tickets x-displayName: Conversas description: Abertura, transferência, encerramento e qualificação de conversas. - name: messages description: Envio assíncrono e leitura de mensagens. - name: tags description: Tags e vínculo com atendimentos. - name: queues description: Filas de atendimento e seus atendentes. - name: wrapups description: Tipos de qualificação. - name: users description: Atendentes e administradores. - name: schedules description: Mensagens programadas. - name: quick-messages description: Respostas rápidas. - name: campaigns description: Disparos em massa. - name: crm description: Painéis, etapas, cards e indicadores. - name: channels description: Canais (somente leitura). - name: reports description: Relatórios e dashboards. - name: products description: Catálogo de produtos, categorias e desempenho nas vendas. - name: custom-fields description: >- Campos personalizados de contato e de card, e variáveis globais da empresa. - name: profiles description: Perfis de permissões da empresa (somente leitura). - name: webchat description: >- Webchat nativo pelo seu sistema: abrir sessão de um visitante, enviar e ler mensagens. O token precisa do escopo `webchat` (GET e POST). paths: /schedules/{id}: parameters: - $ref: '#/components/parameters/idParam' put: tags: - schedules summary: Atualizar agendamento description: > Só é possível editar agendamentos que ainda não foram enviados: | Estado | Editável | Resposta | | --- | --- | --- | | `PENDENTE` | sim | Aguardando o horário. | | `ERRO` | sim | O envio falhou. Editar reprograma o envio. | | `AGENDADA` | não | `409 ERR_API_SCHEDULE_NOT_EDITABLE`. O envio já está na fila. | | `ENVIADA` | não | `409 ERR_API_SCHEDULE_ALREADY_SENT` | | `CANCELADA` | não | `409 ERR_API_SCHEDULE_CANCELED`. Crie um novo agendamento. | Se você trocar o canal de um agendamento com template, envie o `template` de novo. Um template aprovado no canal antigo pode não existir no novo. **Mídia:** em canais de WhatsApp não oficial (`web_whatsapp`, `web_whatsapp_premium`), o arquivo pode ser enviado junto, como `multipart/form-data` no campo `file`. Nesses canais o arquivo é a própria mensagem e o `body` vira a legenda. Com anexo, o texto deixa de ser obrigatório. Em canal oficial, o anexo só é aceito quando o template tem cabeçalho de mídia. Caso contrário, a resposta é `400 ERR_API_TEMPLATE_MEDIA_NOT_ALLOWED`, porque a Meta não aceita anexo avulso. requestBody: required: true content: application/json: schema: type: object properties: sendAt: type: string format: date-time description: > Data e hora do envio, no formato ISO 8601. Precisa ser uma data futura. **Sem fuso, vale o fuso da sua empresa.** `2026-09-15T09:00:00` envia às nove da manhã no fuso configurado na empresa. Com fuso explícito (`2026-09-15T09:00:00-03:00`) ou em UTC (`Z`), o valor é respeitado como está. example: '2026-09-15T09:00:00-03:00' contactId: type: integer description: Contato ao qual este registro pertence. example: 1042 channelId: type: integer description: >- Canal por onde a conversa acontece. Veja os canais disponíveis em `GET /channels`. example: 4 body: type: string description: Texto da mensagem, em canais de texto livre. example: 'Lembrete: sua consulta é amanhã às 14h.' template: allOf: - $ref: '#/components/schemas/TemplateInput' description: >- Template da mensagem, em canais de WhatsApp oficial. É validado de novo a cada atualização. userId: type: integer description: >- Id do usuário nesta empresa, o mesmo que `GET /users` devolve. A mesma pessoa tem um id diferente em cada empresa em que trabalha. example: 3 queueId: type: integer description: Fila de atendimento. example: 7 multipart/form-data: schema: type: object properties: sendAt: type: string format: date-time description: > Data e hora do envio, no formato ISO 8601. Precisa ser uma data futura. **Sem fuso, vale o fuso da sua empresa.** `2026-09-15T09:00:00` envia às nove da manhã no fuso configurado na empresa. Com fuso explícito (`2026-09-15T09:00:00-03:00`) ou em UTC (`Z`), o valor é respeitado como está. example: '2026-09-15T09:00:00-03:00' contactId: type: integer description: Contato ao qual este registro pertence. example: 1042 channelId: type: integer description: >- Canal por onde a conversa acontece. Veja os canais disponíveis em `GET /channels`. example: 4 body: type: string description: Legenda do arquivo anexado. example: 'Lembrete: sua consulta é amanhã às 14h.' userId: type: integer description: >- Id do usuário nesta empresa, o mesmo que `GET /users` devolve. A mesma pessoa tem um id diferente em cada empresa em que trabalha. example: 3 queueId: type: integer description: Fila de atendimento. example: 7 file: type: string format: binary description: >- Arquivo anexo. As regras para cada tipo de canal estão na descrição do endpoint. responses: '200': description: OK content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Schedule' '404': $ref: '#/components/responses/NotFound' '409': description: > O estado atual do agendamento não permite edição. Os códigos possíveis são `ERR_API_SCHEDULE_ALREADY_SENT`, `ERR_API_SCHEDULE_CANCELED` e `ERR_API_SCHEDULE_NOT_EDITABLE`. content: application/json: schema: $ref: '#/components/schemas/Error' '422': $ref: '#/components/responses/UnprocessableEntity' components: parameters: idParam: name: id in: path required: true schema: type: integer example: 1042 schemas: TemplateInput: type: object description: >- Forma **simples** de enviar um template. Você informa o nome e os parâmetros, e o sistema localiza o template no canal, confere se os parâmetros correspondem ao que ele exige e monta a mensagem no formato da Meta. required: - name properties: name: type: string description: >- Nome exato do template aprovado. Consulte em `GET /channels/{id}/templates`. example: confirmacao_pedido language: type: string description: >- Idioma do template. Só é necessário quando existe mais de um template com o mesmo nome em idiomas diferentes. example: pt_BR parameters: type: object properties: body: type: array description: Um item por variável `{{n}}` do corpo, na ordem. items: type: string example: - Maria - '12345' header: type: array description: >- Um item por variável do cabeçalho de texto. Cabeçalho de mídia não usa este campo. items: type: string example: - Marina - '88213' example: name: confirmacao_pedido parameters: body: - Maria - '12345' Schedule: type: object properties: id: type: integer body: type: string sendAt: type: string format: date-time example: '2026-09-15T09:00:00.000Z' sentAt: type: string format: date-time nullable: true status: type: string nullable: true contact: type: object nullable: true description: >- Dados completos do contato, com tags, campos personalizados e campos de marketing. Você não precisa chamar `GET /contacts/{id}` para completar a listagem. allOf: - $ref: '#/components/schemas/Contact' user: type: object nullable: true properties: id: type: integer name: type: string description: Nome exibido. channelId: type: integer nullable: true example: 4 mediaPath: type: string nullable: true mediaName: type: string nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time example: id: 318 body: Oi {{name}}, sua reserva vence amanhã! sendAt: '2026-08-20T13:00:00.000Z' sentAt: null status: pending contact: id: 842 name: Maria Silva number: '5511987654321' numberCountry: BR email: maria.silva@exemplo.com.br code: CLI-00842 cpfCnpj: '12345678909' origin: site profilePicUrl: https://cdn.exemplo.com/avatars/842.jpg isGroup: false instagramUsername: maria.silva lid: null sourceUrl: https://loja.exemplo.com.br/promo sourceId: '23851234567890123' headline: Coleção de inverno mediaType: image mediaUrl: https://cdn.exemplo.com/anuncios/inverno.jpg utmSource: instagram utmMedium: cpc utmCampaign: inverno-2026 utmId: '6543210987' fbclid: IwAR0xYzAbC123 gclid: null ctwaClid: null tags: - id: 3 name: Cliente VIP color: '#6941C6' customFields: - key: plano value: Ouro customFieldId: 91 name: Plano type: select lastChannel: id: 11 name: Instagram Loja type: instagram createdAt: '2026-07-14T13:22:05.412Z' updatedAt: '2026-08-18T09:41:17.883Z' user: id: 3 name: Gabriel Goulart channelId: 11 mediaPath: null mediaName: null createdAt: '2026-08-18T15:10:00.000Z' updatedAt: '2026-08-18T15:10:00.000Z' Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Código fixo do erro, para você tratar cada caso no seu sistema. example: ERR_API_FORBIDDEN_SCOPE message: type: string details: {} Contact: type: object properties: id: type: integer name: type: string description: Nome exibido. number: type: string numberCountry: type: string nullable: true description: >- País do número, no padrão ISO 3166-1 alfa-2. Deduzido do DDI quando o número é gravado pela API. example: BR email: type: string nullable: true example: marina@exemplo.com.br code: type: string nullable: true cpfCnpj: type: string nullable: true example: '12345678909' origin: type: string nullable: true profilePicUrl: type: string nullable: true example: https://cdn.exemplo.com.br/avatar/1042.jpg isGroup: type: boolean description: O contato é um grupo, e não uma pessoa. instagramUsername: type: string nullable: true example: marina.alves lid: type: string nullable: true example: '178452961234567' sourceUrl: type: string nullable: true example: https://loja.exemplo.com.br/promo sourceId: type: string nullable: true example: '23851234567890123' headline: type: string nullable: true example: Coleção de inverno mediaType: type: string nullable: true example: image mediaUrl: type: string nullable: true example: https://cdn.exemplo.com.br/anuncios/inverno.jpg utmSource: type: string nullable: true example: instagram utmMedium: type: string nullable: true example: cpc utmCampaign: type: string nullable: true example: inverno-2026 utmId: type: string nullable: true example: '6543210987' fbclid: type: string nullable: true example: IwAR0xYzAbC123 gclid: type: string nullable: true ctwaClid: type: string nullable: true tags: type: array items: type: object properties: id: type: integer name: type: string description: Nome exibido. color: type: string description: Cor em hexadecimal, com `#`. example: '#6941C6' customFields: type: array description: >- Campos personalizados de contato preenchidos. Sempre vem na resposta, como lista vazia quando o contato não tem nenhum. items: $ref: '#/components/schemas/CustomFieldValue' lastChannel: type: object nullable: true properties: id: type: integer name: type: string description: Nome exibido. type: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time example: id: 842 name: Maria Silva number: '5511987654321' numberCountry: BR email: maria.silva@exemplo.com.br code: CLI-00842 cpfCnpj: '12345678909' origin: site profilePicUrl: https://cdn.exemplo.com/avatars/842.jpg isGroup: false instagramUsername: maria.silva lid: null sourceUrl: https://loja.exemplo.com.br/promo sourceId: '23851234567890123' headline: Coleção de inverno mediaType: image mediaUrl: https://cdn.exemplo.com/anuncios/inverno.jpg utmSource: instagram utmMedium: cpc utmCampaign: inverno-2026 utmId: '6543210987' fbclid: IwAR0xYzAbC123 gclid: null ctwaClid: null tags: - id: 3 name: Cliente VIP color: '#6941C6' customFields: - key: plano value: Ouro customFieldId: 91 name: Plano type: select lastChannel: id: 11 name: Instagram Loja type: instagram createdAt: '2026-07-14T13:22:05.412Z' updatedAt: '2026-08-18T09:41:17.883Z' CustomFieldValue: type: object description: >- Valor de um campo personalizado, junto com a definição do campo. Assim você não precisa chamar `GET /custom-fields` para saber qual é o campo 91. properties: key: type: string nullable: true description: >- Identificador fixo do campo. Use-o para indicar o campo ao gravar valores, porque o `name` pode ser renomeado no painel e a integração deixaria de funcionar sem aviso. value: type: string description: Valor preenchido no campo, no formato definido pelo tipo. customFieldId: type: integer description: Id da definição do campo personalizado. example: 91 name: type: string nullable: true description: Nome exibido. type: type: string nullable: true description: Tipo do campo, que define o formato aceito no valor. example: key: plano value: Ouro customFieldId: 91 name: Plano type: select responses: NotFound: description: >- O recurso não existe ou pertence a outra empresa. Por segurança, a resposta é a mesma nos dois casos. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_NOT_FOUND message: Registro não encontrado. UnprocessableEntity: description: >- O corpo está bem formado, mas falta um campo obrigatório ou algum valor não é aceito. Por exemplo, `application` diferente de `contact`/`card`, `orderedIds` vazio ou `name` em branco. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_VALIDATION message: >- O parâmetro `application` é obrigatório e aceita "contact" ou "card". securitySchemes: apiToken: type: http scheme: bearer description: Token da API no formato `sk_live_…`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.